How to update Taweret documentation

We use the sphinx documentation system to encode and manage the documentation for our Python package. The official documentation is published by read the docs, test builds are made available in PRs by read the docs, and users can build and access locally the documents using our tox setup. In addition, HTML and PDF-format builds of the documentation are available for download as artifacts from documentation build GitHub actions.

sphinx uses reStructuredText as the plaintext markup language. You might find this cheatsheet useful. You can also refer to sphinx website for more information.

Structure

docs/source/index.rst determines the overall structure of the documentation. Each file that is referenced in index.rst can be found in the same folder. For example, if you want to modify the general introduction documentation, change docs/source/intro.rst.

Inline documentation of Python code in the package is automatically built into the documentation based on the content of the sphinx-based inline docstrings associated with the code itself (i.e., the Python files are self-documenting). Therefore, there should be no need to alter any of the .rst files to include your inline documentation unless you are adding in new subpackages or altering the structure of the package. In such cases, please contact one of the core Taweret developers for help.

Developers should not add or commit anything in the docs/build_pdf or docs/build_html folders, to which local documentation build results are written.

Building

While the generation and publishing of the sphinx documentation is automated and includes sanity checks to confirm correct building, there is no automation that confirms correctness of the content. Our git workflow has been designed to help maintain the documentation up-to-date and correct.

TODO: Add in information regarding how documentation is managed within the general git workflow to motivate and provide context for the following.

To help developers interactively improve the documentation and manually confirm correct content and rendering, we suggest that developers use the tox documentation tasks html and pdf to locally visualize their changes. Please refer to tox Development Environments for more information. For those developers who prefer to avoid tox, please read tox.ini to determine how to setup and use your environment manually for building documentation.