Maintaining this Documentation¶
Overview¶
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 html
will build the docs locally. Verify any changes by viewing_build/html/index.html
Any new docs should be directly or indirectly linked to from
index.rst
. (For example, ifindex.rst
containsbalrog/index.rst
in its toctree, and the new doc is in thebalrog/index.rst
toctree, then the new doc is successfully indirectly linked.)We support both markdown
.md
and reStructuredText.rst
files. 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¶
Warning
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: