Sphinx
Resources
Quick Start
pip install Sphinx
mkdir docs
cd docs
sphinx-quickstart
This creates:
Versioning
Instead of hardcoding version in the quick start wizard, use the python __version__ dunder to have the version automatically be pulled.
Building The docs
sphinx-build . _build/html/
make html # this is just an alias to the above command
Instead of just detecting changes you might want to rebuild the whole thing:
sphinx-build -E . _build/html/
make clean; make html
Code Coverage
can use a different build tool addon that is activated from the quickstart wizard called coverage
sphinx-build -b coverage . _build/coverage/`
This will use coverage as the build tool and tell you when you have undocumented functions. Otherwise sphinx will fail quietly because if there's no work to do (functions dont have doc strings) then it fails quietly.
There is a flag to get it to process and render function documentation even if its blank called undock members but coverage gives insight into undocumented things.
Themes
pip install sphinx_rtd_theme # this is for read the docs theme
and then inside conf.py in the docs/ directory:
html_theme = 'sphinx_rtd_theme'
Children
Backlinks