Python continuous documentation
A well-documented Python library is something to be proud of. Reading through the code, you've got docstrings explaining the various parameters and constraints around your functions, hopefully using standards like Sphinx or Google formatting. Having to open up the code to find this information is less than ideal, but it's easy to turn these docstrings into beautiful, hosted HTML, updated every time you push to GitHub.
We'll be taking advantage of plenty of different technologies to make this happen:
- ReadTheDocs manages the builds, versions, and hosts your docs.
- Sphinx with autodoc renders your docs.
- GitHub or BitBucket hook into ReadTheDocs to trigger builds whenever code is commited.
Before we get started, head over to ReadTheDocs and create an account, if you don't have one already. It's a free, open-source service. You can even spin up your own private instances, although their documentation for doing that isn't the best :)
Setting Up Your Project
As always, I suggest using a virtualenv for local Python development! Inside your virtualenv, run:
pip install sphinx
doc/ directory in your project, we'll add it to git later:
mkdir -p doc cd doc
Create the basic configuration and file structure:
There are several questions I suggest giving a non-default answer to:
> Separate source and build directories (y/N) [n]: y > Project name: yourproject > Author name(s): Your Name > Project version: 1.2.3 > autodoc: automatically insert docstrings from modules (y/N) [n]: y > intersphinx: link between Sphinx documentation of different projects (y/N) [n]: y
Creating the Doc Layout
sphinx-quickstart, you specified
index.rst as the starting
point for your documentation pages. With Sphinx, you'll need every page linked
either directly or indirectly from
index.rst using the
directive. Let's consider the following Python package:
docpkg/__init__.py docpkg/main.py docpkg/config.py
One package, three modules. Replace your
index.rst with the following:
``docpkg`` Package ================== .. automodule:: docpkg :members: ------------------- **Sub-Modules:** .. toctree:: docpkg.main docpkg.config
Now we're going to create two more files,
docpkg.config.rst. I'll give you
docpkg.config.rst the same way:
``docpkg.main`` Module ======================== .. automodule:: docpkg.main :members:
As you add more modules to your project, they need to be added to the
documentation structure. You can obviously put more than one
on a page, at your discretion.
Building the Docs Locally
Once you have your doc layout created, you can build your documentation from the
doc/ directory with:
Now, just navigate to
doc/build/html/index.html in your browser!
Committing to Git
doc/ directory tree does not necessarily need to be put into git.
The following should suffice:
git add doc/Makefile doc/source/conf.py doc/source/*.rst
Setting Up ReadTheDocs
Once you've created an account and logged in to ReadTheDocs, go to your Dashboard and click the "Import" button. Most of your choices will depend on your project, although you will need to set these three options in particular:
- Repo: Use the
https://<repo-url>.gitlink to your Git repository!
- Python configuration file:
- Use virtualenv: ✓
Once you've created your project, check your Builds tab for failure information. It may take some troubleshooting to get a Success, but usually these are solvable with tweaks to your package, for example making sure it pulls all its own dependencies in correctly.
Version Control Webhook
Now that you've got your documentation building on ReadTheDocs, you want your documentation rebuilt as you update your code (and docstrings!). This step is crucial, don't skip it! If rebuilding your documentation is a manual step, just admit it, it won't happen often.
Both GitHub and BitBucket have builtin webhooks for ReadTheDocs, under your project's settings. Just activate them and you're good to go.
For other version control systems, you may need to work something else out. If you look on your ReadTheDocs project page and find the "Post Build Hook" URL, it can be hit to trigger documentation rebuilds.
Frequently Asked Questions
Q: How do I link to other projects?
A: This is one of my favorite parts of Sphinx, the ability to link
directly to classes, functions, and modules in third-party projects on the
Internet. We can do this because we enabled the
intersphinx extension, see
its documentation for its use. You can link to projects hosted anywhere,
not just other ReadTheDocs projects!
Q: What happens if my project depends on non-Python code?
A: Some projects may require things like C libraries to be installed,
which cannot be brought in automatically with
pip. The ReadTheDocs build
servers have many of these packages already installed.
Q: Does my project meet the requirements?
A: If you have a
setup.py with an
"install_requires" field to pull in
its own dependencies from PyPi, that should be all you need! If your
project does not have a
setup.py, it's dependencies can be installed using a
pip requirements file.
Q: Is it only for documenting code?
A: You can easily add items to your
.. toctree:: with anything you
want, such as usage manuals or code samples. Sphinx documentation is built
using their heavily extended reStructuredText markup, so anything you can
concoct with this powerful syntax is possible.