mirror of
https://github.com/tahoe-lafs/tahoe-lafs.git
synced 2024-12-29 17:28:53 +00:00
74 lines
3.2 KiB
Plaintext
74 lines
3.2 KiB
Plaintext
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.
|
|
|
|
Note that Sphinx can also process Python docstrings to generate API
|
|
documentation. Tahoe-LAFS currently does not use Sphinx for this
|
|
purpose.
|
|
|
|
|
|
Organizing Tahoe-LAFS documentation
|
|
-----------------------------------
|
|
|
|
Tahoe-LAFS documentation has been a mishmash of many things that are
|
|
useful to many people, with little organization, and, as a result,
|
|
confusing and hard-to-approach. We are working on improving this.
|
|
|
|
It is reasonable to expect that documentation files in "docs"
|
|
directory will serve different and possibly overlapping groups of
|
|
readers, so the top-level sections are organized based on the likely
|
|
needs of those almost-distinct groups. We have:
|
|
|
|
(a) New and experienced users of Tahoe-LAFS, who mainly need an
|
|
operating manual to the software. Sections on "Introduction"
|
|
and "Using Tahoe-LAFS" will be the most useful to them.
|
|
|
|
(b) Project contributors, both new and experienced. This group
|
|
includes developers, issue reporters, and documentation writers.
|
|
It will help this group to have the project's processes and
|
|
guidelines written down. The section titled "Contributing to
|
|
Tahoe-LAFS" is meant to be useful for this group.
|
|
|
|
(c) Those who want to know various implementation details about the
|
|
project. This group might include people who are mainly curious
|
|
and those who want change things. We could expect an overlap
|
|
between members of group (a) who want to know more and members
|
|
of group (b). The sections titled "Tahoe-LAFS in Depth" and
|
|
"Specifications" could be of interest to them.
|
|
|
|
(d) There's also the broader community. This includes people with a
|
|
general interest in Tahoe-LAFS project, and people from groups
|
|
both (a) and (b). They will find "Notes of Community Interest"
|
|
useful.
|
|
|
|
When you add new content or remove old content to Tahoe-LAFS docs, it
|
|
would be helpful to organize your changes with the above-stated groups
|
|
of readers in mind.
|
|
|
|
This directory also contains old notes that are mainly of historical
|
|
interest, under the section titled "Notes of Historical Interest".
|
|
Those could be removed someday, after sufficient consideration.
|