-
Make sure you have installed all dependencies used by the project. This is easily accomplished with
pip install <module_name>
-
See First Steps with Sphinx for an overview on how Sphinx works. Essentially, Sphinx uses a markup language called reStructuredText to create nice looking documentation. It will be helpful to read about the function of the master document
index.rst
so that you can understand how thetoctree
works. -
Install Sphinx with
pip install sphinx
-
To get Sphinx setup,
sphinx-quickstart
. This will ask several questions about the project. To make the file tree cleaner, I think it's good to separate the respond toSeparate source and build directories (y/n)
withy
. Sphinx's Autodoc extension automatically generates the reStructuredText needed for Sphinx to build the documentation from docstrings, so when askedautodoc: automatically insert docstrings from modules (y/n)
, respondy
. -
In order to generate documentation using Google-style docstrings, we need to use the Napoleon extension. In order for Napoleon to work, we need to edit
conf.py
to include the following information:
extensions = [
'sphinx.ext.autodoc',
'sphinx.ext.napoleon'
]
napoleon_google_docstring = True
napoleon_numpy_docstring = False
napoleon_include_init_with_doc = True
napoleon_include_private_with_doc = False
-
As explained in An Idiot's Guide to Python Documentation with Sphinx and ReadTheDocs, we can automatically generate the necessary reStructuredText by calling
sphinx-apidoc -o source/ ../<package_name>
. This will create a few.rst
files with directives telling autodoc what files it should create documentation from. -
In order for Sphinx to know it should act on the directives in these new
.rst
files, they need to be added to thetoctree
inindex.rst
. Basically, you just editindex.rst
and add the names of the new.rst
files below the line reading.. toctree::
. For example, if we just want to document a package contained in a single folder calledpackage
, we thetoctree
directive in ourindex.rst
file might look like this:
.. toctree:
:maxdepth: 2
package
modules
- Before we can build the documentation, we need to make sure Sphinx knows where to get the modules from. In
conf.py
, the following three lines are commented out by default:
import os
import sys
sys.path.insert(0, os.path.abspath('.'))
As noted in a stackoverflow post about this, if our project has the structure
project
| docs/
| project/
| project files, etc.
| tests/
we need to uncomment those three lines in conf.py
and change the third line about changing the path to sys.path.insert(0, os.path.abspath('../..'))
.
-
Now, we're ready to build the documentation. To create HTML documentation, go to the directory with
Makefile
and callmake html
. This will create a folderbuild/html/
with the documentation. To view it, go to that directory and launch python's simple web server usingsudo python -m SimpleHTTPServer 80
, which will host the documentation website on your local machine. You can then navigate to the webpage by going tolocalhost
in your browser. -
For details on how to use the ReadTheDocs Theme, see Read the Docs Sphinx Theme