The official guide to Sphinx can be found here. This is another helpful guide.
If you have cloned the OpenCMP repository, you should have all the necessary Sphinx configuration files already set up. Try the following steps:
Install Sphinx with
apt-get install python3-sphinx. Make sure you install for Python 3.6+.
Check if you have “docs/_static” and “docs/_templates/” directories. If you don’t, create empty directories with these names.
Within the “docs” directory in the main OpenCMP directory run
Move to the “docs/_build/html” directory and open any of the .html files (“index.html” is a good one to start with).
If any of the above steps don’t work, run
sphinx-quickstart as detailed in the official guide then modify the “conf.py” file as described in the next section.
The following lines must be uncommented or added to the top of the file.
import os import sys sys.path.insert(0, os.path.abspath('.')) sys.path.insert(0, os.path.abspath('../'))
sphinx.ext.napoleon to the end of
extensions so Sphinx can parse Google-style docstrings. The following lines also need to be added directly below
napoleon_google_docstring = True napoleon_include_private_with_doc = True napoleon_use_param = True napoleon_use_rtype = True
To make Sphinx play nicely with typing add
extensions. This must be included after
sphinx.ext.napoleon or it won’t work.
Set the Sphinx theme to the ReadTheDocs theme with
html_theme = 'sphinx_rtd_theme'. The theme can be installed with
pip3 install sphinx_rdt_theme.
Some OpenCMP documentation uses Markdown, which must be parsed into reStructuredText using recommonmark before it can be read by Sphinx. Install recommonmark with
pip3 install --upgrade recommonmark then add
extensions. Finally, add
.md to the
ASCII art is made with aafigure. Install aafigure with
pip3 install aafigure then add
If using Markdown, the file titles must be denoted by underlining with “=”. Sphinx doesn’t recognize “#” and will give an error about a missing title.
If Sphinx is displaying old docstrings or failing to find modules that have been renamed or removed, delete the “source” directory and then run
sphinx-apidoc -o source/ ../from within the “docs” directory. This will recreate the automatic docstring documentation from the current code base.
make cleanclears anything cached in the “_build” directory.