Menu

Subscribe

Documenting your project with Sphinx

Setup:

  1. Get started
  2. Add a better theme
  3. Autodoc
  4. 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:

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.

References