How to set up this sweet documentation workflowΒΆ
Purely for informing other projects in the future. Users and developers on this project do not have to do any of this. It is setup for you.
Install what you need into your virtual environment:
$ pip install Sphinx $ pip install sphinx_rtd_template $ pip install sphinxcontrib-napoleon $ pip freeze > requirements.txt
Set up the sphinx project:
$ sphinx-quickstart
Advanced configure within the
conf.py
fileSpecify extensions. I use these:
extensions = ['sphinx.ext.autodoc', 'sphinx.ext.napoleon', 'sphinx.ext.todo', 'sphinx.ext.mathjax', 'sphinx.ext.ifconfig', 'sphinx.ext.viewcode']
Configuration of Napoleon:
napoleon_google_docstring = True napoleon_use_param = True
Configuration of Autodocumentation:
autodoc_member_order = 'bysource' autoclass_content = 'both'
Template configuration for readthedocs style:
import sphinx_rtd_theme html_theme = 'sphinx_rtd_theme' html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
Mock up for external modules imported in your code:
import sys from unittest.mock import MagicMock class Mock(MagicMock): @classmethod def __getattr__(cls, name): return MagicMock() MOCK_MODULES = ['numpy', 'matplotlib', 'matplotlib.pyplot', 'matplotlib.figure', 'scipy', 'scipy.optimize'] sys.modules.update((mod_name, Mock()) for mod_name in MOCK_MODULES)
Further documentation here