Maintaining this Documentation¶
Release Engineering has a wide variety of documentation, served from various locations. Per Releng RFC 0007, we want to use this as a central location for Release Engineering documentation, but will link to other locations from here when that makes sense.
We likely need to go through these docs and clean up.
Building the docs locally¶
Create a python virtualenv
pip install -r rtfd-requirements.txt
make htmlwill build the docs locally. Verify any changes by viewing
Any new docs should be directly or indirectly linked to from
index.rst. (For example, if
balrog/index.rstin its toctree, and the new doc is in the
balrog/index.rsttoctree, then the new doc is successfully indirectly linked.)
We support both markdown
.rstfiles. The former may be simpler to write and use; the latter have more powerful linking and nesting capabilities. See the Sphinx docs for documentation.
Documenting Source Code¶
old instructions; we may want to revisit!
We use Sphinx to generate our code documentation, and host it on Read the Docs. There are two major phases to this: