Sphinx documentation setup - cma-open/cmatools GitHub Wiki

Using Sphinx the package documentation is automatically generated

Key files:

The sphinx documentation files in this repo, and the associated scripts can be used as a starting template to create similar custom documentation.

The process to set up this documentation was:

Initial setup
- sphinx and extensions were installed in the conda environment
- quickstart was run to create initial setup and template files
  - see https://www.sphinx-doc.org/en/master/usage/quickstart.html
- conf.py file was edited to select the theme and add extensions, see docs/source/conf.py
  - key selections were: sphinx_rtd_theme and the use of numpydoc, autosummary and autodoc extensions
- at the end of this process an index.rst file will exist in docs/source
Editing source text files within docs/source
- manually edit index.rst to list the key pages that will appear in the initial table of contents (toc), customise the layout as required
- add any required subdirectories in the source directory (e.g. userguide)
- manually add any required .rst pages into the newly added subdirectories, e.g. "userguide" (holds all manually generated userguide docs)
- ensure all manually added pages are added to be listed in the index.rst
Automation and page hosting
- a script was created to build the documentation
  - scripts/build-sphinx-docs.sh
- autosummary with recursion was used to automatically generate the fill range of documentatino for python package/library/api
- template files were used to modify the layout of the files created
  - see here and here
- edited templates are in / docs/source/_templates
- a github pipeline was created to automatically publish the documentation to the gighub pages site

Options / Notes

Members (Functions, classes etc) with no docstrings will NOT be documented unless undoc flag is used, undoc-members
Private (non public) members are not documented by default , private-members
Section and pages can be referenced a directly by section title, e.g. :ref:section-title.

Example package with a similar docstring style and documentation output

Other example sites using sphinx

Refs