Setup:
- Get started
- Add a better theme
- Autodoc
- Autobuild
Getting started
Using sphinx is pretty easy:
Install with pip:
pip install sphinx
Run the quickstart:
sphinx-quickstart
Notes:
- I like to set the root path for documentation to:
docs
. The rest of this tutorial will assume that you have also installed your sphinx docs into a docs folder
just like that .. you have your documentation setup. You can build your docs by running:
make html
from your docs
folder
Source: First Steps with Sphinx
Add a better Theme
I don't really like the default theme, I think the one over at ReadTheDocs is much better.
Adding it is a breeze:
pip install sphinx_rtd_theme
Then update your conf.py
file (docs/source/conf.py
):
Find html_theme = 'default'
and replace this with:
import sphinx_rtd_theme
html_theme = "sphinx_rtd_theme"
html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
Rebuild your docs with make html
, and you should see a much prettier looking version of your docs
Autobuild
It can be quite annoying to have to keep updating the docs everytime you make a change, it would be nice if it could auto-build. Fortunately, there's a plugin for that:
pip install sphinx-autobuild
Now, from inside our docs
folder, we can run autobuild with:
sphinx-autobuild source build/html
This will load up your docs on a server 127.0.0.1:8000. If you have the Chrome Live Reload plugin installed, it will even refresh your browser everytime you change your files.
Note:, if you want to run on a different port, use the -p
switch. e.g.:
sphinx-autobuild source build/html -p3000
Source: sphinx-autobuild
Bonus: publish your docs automatically with Jenkins
To do this, you need to install two plugins:
- Shining Panda plugin - gives you python virtualenvs
- HTML Publisher Report
Add the following to a virtualenvbuilder step:
pip install sphinx
pip install sphinx_rtd_theme
cd docs && make html
Add a post build action of type: "publish html report". Set:
- Directory:
docs/build/html/
- Index page:
index.html
Now, if you build, you should see a report attached to your job dashboard.