Bryson Tyrrell Your Code Should Document Itself Embedding Documentation into Your Python Projects
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'
Public Documentation
can link to publix github projects and when you successfully commit into a branch it will rebuild your docs on the readthedocs site.
Private Docs
In Pipelines i can build the docs and return an artifact and deploy that artifact somewhere afterwards
Backlinks