Sphinx Autodoc - note to self


Napoleon is a Sphinx Extensions that enables Sphinx to parse both NumPy and Google style docstrings - the style recommended by Khan Academy.

Make sure to include the extension in the conf.py add the following extensions

extensions = ['sphinx.ext.autodoc', 'sphinx.ext.napoleon']

Set the Python path

In order to generate the documentation, we need to tell Sphinx where it can find our code.

sys.path.insert(0, os.path.join(os.path.abspath('.'), 'petfactory'))

Mock imports

To mock claases that are not available when we do the documentation we can use mock (confy.py)

import mock
sys.modules['PySide2'] = mock.Mock(QtWidgets=object)

We can also use autodoc_mock_imports, but I have noticed the if we extend a mocked class the documentation will not be generated.

autodoc_mock_imports = ['pymel', 'pyside2']


We can use apidoc to automatic generate .rst files. We need to specify the -o (output, where we want the .rst files to be created) followed by the path to the python package or module we want to create the .rst files for.

We can give it the root package path and it will recursively traverse the package/module structure and create the .rst files.

# -e, --separate	Put each module file in its own page.

$ sphinx-apidoc -e -o .  petfactory


$ pip install sphinx_rtd_theme
import sphinx_rtd_theme

html_theme = "sphinx_rtd_theme"

html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]