Recently I’ve been working on a python project and decided to use the highly-praised Sphinx package to generate useful and beautiful documentation for it. Unfortunately I found Sphinx’s own documentation to be a somewhat lacking – which is kind of ironic if you ask me. Anyway, here are the steps I found to go from “A dirty pile of python code with no documentation at all” to “A dirty pile of python code with beatifully formated sphinx-generated documentation.”
1. Put sphinx-readable documentation into your code.
This is fairly straightforward.
Under the declaration for each module, class, and function put a few lines of documentation code. With Sphinx you have two options (AFAIK) – google styled docstrings according to Google’s Python Styling Guide or sphinx styled docstrings. The sphinx documentation gives a good run-down of these styles.
I went with the Google-styled documentation because it’s a lot more readable within the code itself, but I do miss some of the more readable styling from the generated documentation. So it’s up to you to figure out what you think is most important for your project.
2. Install sphinx
I used pip.
sudo pip install sphinx
It worked. It was awesome.
3. Run sphinx-quickstart from the root folder for documentation
Sphinx-quickstart is an interactive prompt that generates most of the files you will need for sphinx documentation. It will prompt you for your project name, your name, the version, etc.
I followed the sphinx documentation on this one. I did it twice, opting both to generate a Makefile and not. The Makefile seemed pretty useful.
4. Run sphinx-apidoc on my package folder
This is the first required step that I couldn’t really find much info on in Sphinx’s official documentation.
Sphinx-apidoc runs through your python files and generates a .rst file for each of the modules included in your project. These files are what tells sphinx to what it needs to include in the final html or pdf documentation.
The sphinx-apidoc command requires an input directory – i.e. the directory with your source code, and an output directory – which should be the source directory generated by sphinx-quickstart. Like this:
sphinx-apidoc -o <path-to-sphinx-source> <path-to-python-files>
4. Add the generated .rst files to index.rst
When you ran sphinx-quickstart in step 3 it should have generated an index.rst file in the source directory. This file defines what the index of your documentation tree looks like. After you generated additional .rst files for your projects modules, you need to add them to the index.rst file so that sphinx will link to the documentation you included in your source code.
Initially your index.rst file will look like this:
your-project-name ===================================== Contents: .. toctree:: :maxdepth: 2 Indices and tables ================== * :ref:`genindex` * :ref:`modindex` * :ref:`search`
You need to add the files generated from sphinx-apidoc in the contents section. Do not include the .rst extention
your-project-name ===================================== Contents: .. toctree:: :maxdepth: 2 name-of-file1-generated-by-sphinx-apidoc name-of-file2-generated-by-sphinx-apidoc ... Indices and tables ================== * :ref:`genindex` * :ref:`modindex` * :ref:`search`
5. Add your source code directory to your path in conf.py
Lastly you need to make sure sphinx can find your soure code. To do this you need to include them in sphinx’s path. This can be done by adding a line to the conf.py file in sphinx’s source directory with the relative path.
import sys
import os
# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
sys.path.insert(0, os.path.abspath('../../.'))
6. Run sphinx-build or make
If everything is setup correctly you should be rewarded with a set of well-formatted html files documenting your code.
