Built using sphinx.
Uses the sphinx autodoc extension to automatically generate API documentation. This module imports the modules and reads the documentation for each function and generates the API documentation based on that.
Uses the sphinx epytext extension to convert older style epydoc documentation format to sphinx readable.
I also have it set to use recommonmark in case any one wants to use markdown really badly.
It also uses the default sphinx.ext.viewcode to insert links to the related source code.
You'll need the following python packages (and dependencies). From my command history getting it up and running;
git clone https://github.com/sebastiansam55/autokey-sphinx
cd autokey-sphinx
git clone https://github.com/autokey/autokey
cd autokey
pip install .
cd ..
pip install sphinx recommonmark sphinx-rtd-theme sphinx-epytext enum-tools[sphinx]
# for first time installs you'll likely have to restart your shell for the sphinx-build command to be found.
# should be run from the base of this repository
sphinx-build -a -E -b html . ./docs
Basic workflow:
- Installs Git
- Clones autokey/autokey (master branch)
- Installs Autokey using
pip install .in autokey repo - Installs sphinx
pip install sphinx recommonmark sphinx-rtd-theme sphinx-epytext
- Builds sphinx site
sphinx-build -a -E -b html ./ docs
- Uploads pages Artifact (docs output folder)
- Deploys to Github Pages for this repository
When a pull request is merged in, its action will need to be run manually to apply the changes by rebuilding the documentation pages:
- Go to Build Autokey pages
- Press the Run button
- Wait for the process to finish.
There is a plugin that supports versioned documentation, sphinxcontrib-multiversion which seems to be decently well maintained.
Going forward we should use sphinx syntax in comments instead of older epytext.; https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html
For more information on the new comment markup.