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 may be built by running the following commands from the doc folder:

$ make apidoc
$ make relnotes
$ make html

The HTML output is available in the doc/_build folder. 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!

Dependencies

In order to build the HTML version of the documentation, you must have the Python packages listed the docs-requirements.txt installed, i.e.

numpydoc>=1.5.0
pydata-sphinx-theme>=0.13.3
sphinx>=7.2.5
sphinx-design>=0.5.0
myst-parser>=2.0.0

Also, in order to run the above make commands, you muse have make installed.