tahoe-lafs/trac-2024-07-25

publish docs to readthedocs.org #2753

New issue

Closed

opened 2016-03-22 19:07:15 +00:00 by warner · 2 comments

warner commented

2016-03-22 19:07:15 +00:00

Owner

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.

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.