Merge pull request #997 from sajith/3630.update-docs-readme

Update notes about reading/writing docs

Fixes: ticket:3630

docs/README.txt

@@ -1,7 +1,30 @@
+If you are reading Tahoe-LAFS documentation
+-------------------------------------------
 
-Note: http://tahoe-lafs.readthedocs.io/en/latest/ is the preferred place to
+If you are reading Tahoe-LAFS documentation at a code hosting site or
-read this documentation (GitHub doesn't render cross-document links or
+from a checked-out source tree, the preferred place to view the docs
-images). If you're reading this on https://github.com/tahoe-lafs/tahoe-lafs ,
+is http://tahoe-lafs.readthedocs.io/en/latest/. Code-hosting sites do
-or from a checked-out source tree, then either run `tox -e docs` and open
+not render cross-document links or images correctly.
-_build/html/index.html in your browser, or view the pre-rendered trunk copy
+
-at http://tahoe-lafs.readthedocs.io/en/latest/
+
+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.
+
+Note that Sphinx can also process Python docstrings to generate API
+documentation. Tahoe-LAFS currently does not use Sphinx for this
+purpose.