[tahoe-lafs-trac-stream] [Tahoe-LAFS] #2753: publish docs to readthedocs.org

[Tahoe-LAFS]

#2753: publish docs to readthedocs.org
---------------------------+------------------------
 Reporter:  warner         |          Owner:  daira
     Type:  task           |         Status:  new
 Priority:  normal         |      Milestone:  1.12.0
Component:  documentation  |        Version:  1.10.2
 Keywords:  docs           |  Launchpad Bug:
---------------------------+------------------------
 Currently, the best way to read the Tahoe docs is either from a source
 tree (git, or unpacked tarball), or online on github. Only the latter
 provides any formatting of the .rst files.

 Most other Python projects (and quite a few non-python ones) are
 publishing their docs to readthedocs.org . They do an rst-to-HTML build
 step that adds nice things like a table of contents, and a clear way to
 find docs for specific versions.

 I'd like to figure out how to publish our docs that way too. Then I think
 we can start on some organizational improvements, to make the docs more
 like an instruction manual and less like a haphazard collection of design
 notes. The .rst source will still live in `docs/`, but we'll use the
 README and the Trac wiki front page to point people at readthedocs.org
 instead.

 I don't know what mechanics are involved. I believe it will need some new
 .rst files (for the TOC and front-matter), and maybe something in the
 buildbot to trigger pushes to readthedocs.org on each commit/release.

--
Ticket URL: <https://tahoe-lafs.org/trac/tahoe-lafs/ticket/2753>
Tahoe-LAFS <https://Tahoe-LAFS.org>
secure decentralized storage