Reference documentation

The cotainr reference documentation is what you are reading right now. It consists of a set of reStructuredText files in the doc folder along with all the docstrings in the cotainr Python source code, and the markdown release notes in the doc/release_notes folder. All of it is tied together via a Sphinx setup for building an HTML version of the documentation which is hosted on http://cotainr.readthedocs.io.

Building the HTML version

The HTML version of the documentation can be built locally for development. First install the required dependencies specified in pyproject.toml. This can be done with uv,

$ uv sync --group docs

the documentation may then be built by running the following make commands in the doc folder

$ uv run make apidoc
$ uv run make relnotes
$ uv run make html

The HTML output is available in the doc/_build folder and can be inspected in a browser such as firefox,

$ firefox _build/html/index.html

The make apidoc command generates reStructuredText files for the API reference documentation. These files include sphinx.ext.autodoc directives that automatically generate the API reference documentation from the docstrings of the modules/classes/functions/… in cotainr. The make relnotes command generates the list of release notes from the markdown files in the doc/release_notes folder.

The HTML version of the documentation is based on the PyData Spinx Theme and its design and layout is heavily inspired by the NumPy, SciPy, and Pandas documentations - a big shout-out to the people who created those documentation designs!