tahoe-lafs/docs/README.txt

If you are reading Tahoe-LAFS documentation
-------------------------------------------

If you are reading Tahoe-LAFS documentation at a code hosting site or
from a checked-out source tree, the preferred place to view the docs
is http://tahoe-lafs.readthedocs.io/en/latest/. Code-hosting sites do
not render cross-document links or images correctly.


If you are writing Tahoe-LAFS documentation
-------------------------------------------

To edit Tahoe-LAFS docs, you will need a checked-out source tree. You
can edit the `.rst` files in this directory using a text editor, and
then generate HTML output using Sphinx, a program that can produce its
output in HTML and other formats.

Files with `.rst` extension use reStructuredText markup format, which
is the format Sphinx natively handles. To learn more about Sphinx, and
for a friendly primer on reStructuredText, please see Sphinx project's
documentation, available at:

https://www.sphinx-doc.org/

If you have `tox` installed, you can run `tox -e docs` and then open
the resulting docs/_build/html/index.html in your web browser.

If you have Sphinx and Make installed, you can also run `make html`
within the docs directory. You may also need to install some
additional Python packages, such as `setuptools` and `recommonmark`.

Note that Sphinx can also process comments in Python source code to
generate API documentation. Tahoe-LAFS currently does not use Sphinx
for this purpose.
Update notes about reading/writing docs 2021-03-09 20:02:32 +00:00			`If you are reading Tahoe-LAFS documentation`
			`-------------------------------------------`
docs: clean up .rst and references This uses Read-The-Docs (sphinx/docutils) references exclusively, but adds a README.md for GitHub viewers to remind them that the links there won't work (closes ticket:2835). It also fixes all the dangling references and other Sphinx warnings. The "Preparation" section of docs/magic-folder-howto.rst was removed, since this feature has since been merged to trunk. 2016-12-12 21:48:13 +00:00
Update notes about reading/writing docs 2021-03-09 20:02:32 +00:00			`If you are reading Tahoe-LAFS documentation at a code hosting site or`
			`from a checked-out source tree, the preferred place to view the docs`
Use one space after period 2021-03-23 14:17:20 +00:00			`is http://tahoe-lafs.readthedocs.io/en/latest/. Code-hosting sites do`
Update notes about reading/writing docs 2021-03-09 20:02:32 +00:00			`not render cross-document links or images correctly.`


			`If you are writing Tahoe-LAFS documentation`
			`-------------------------------------------`

Use one space after period 2021-03-23 14:17:20 +00:00			`To edit Tahoe-LAFS docs, you will need a checked-out source tree. You`
Update notes about reading/writing docs 2021-03-09 20:02:32 +00:00			can edit the `.rst` files in this directory using a text editor, and
			`then generate HTML output using Sphinx, a program that can produce its`
			`output in HTML and other formats.`

"The files with ..." to "Files with ..." 2021-03-23 14:18:25 +00:00			Files with `.rst` extension use reStructuredText markup format, which
			`is the format Sphinx natively handles. To learn more about Sphinx, and`
			`for a friendly primer on reStructuredText, please see Sphinx project's`
			`documentation, available at:`
Update notes about reading/writing docs 2021-03-09 20:02:32 +00:00
			`https://www.sphinx-doc.org/`

tox to `tox` 2021-03-23 14:34:46 +00:00			If you have `tox` installed, you can run `tox -e docs` and then open
			`the resulting docs/_build/html/index.html in your web browser.`
Update notes about reading/writing docs 2021-03-09 20:02:32 +00:00
			If you have Sphinx and Make installed, you can also run `make html`
`docs directory` to `the docs directory` 2021-03-23 14:35:30 +00:00			`within the docs directory. You may also need to install some`
`setuptools` and `recommonmark` 2021-03-23 14:36:06 +00:00			additional Python packages, such as `setuptools` and `recommonmark`.
Update notes about reading/writing docs 2021-03-09 20:02:32 +00:00
			`Note that Sphinx can also process comments in Python source code to`
Use one space after period 2021-03-23 14:17:20 +00:00			`generate API documentation. Tahoe-LAFS currently does not use Sphinx`
Update notes about reading/writing docs 2021-03-09 20:02:32 +00:00			`for this purpose.`