Adding Sphinx docs to Existing Repositories#
So, you need to add some docs for code that we’ve already written. You’ve come to the right place!
- There are two common “setup” scenarios:
No mater where you start, there are some common enhancements to improve the generated output.
In a nutshell, we use Sphinx with documentation placed in the
docs
directory off the root of the project.
Adding Sphinx to a project with no docs yet#
Make sure Sphinx is installed on your machine (it shouldn’t be in your project’s virtual environment). From the top level project directory, run:
sphinx-apidoc -F -A "RelEng Team" -V "0.1" -o docs $python_module_name
If you happen to have an early stage project, without a python module
directory yet, GOOD FOR YOU!!! You’ll just do the normal
sphinx-quickstart
. Please keep the defaults, except for ‘autodoc’
and ‘viewcode’ (say ‘Y’/Yes to both):
sphinx-quickstart docs
No matter which way you add Sphinx, don’t forget to add docs/_build
to the project’s .hgignore
or .gitignore
file.
Adding autodoc to a project already using Sphinx#
The following command should maintain you existing docs, while adding the generated code documentation. From the top directory:
sphinx-apidoc -o docs $python_module_name
This will produce a file modules.rst
which you’ll need to manually
add into your existing index.rst
file.
Tweaking the conf.py file#
After you’ve added generated documentation to your Sphinx project,
you’ll also need to tweak the generated docs/conf.py
file needs a
couple of edits to work properly. Around line 21, add the following
lines:
sys.path.insert(0, os.path.abspath('..'))
import mock
MOCK_MODULES = []
for mod_name in MOCK_MODULES:
sys.modules[mod_name] = mock.Mock()
The first line ensures the module under development is found. The remaining lines are a handy framework for satisfying import requirements for your module.
Note
If you want to import the real code during document generation, you’ll need to add it to the read-the-docs requirements file, if it isn’t already in your project’s requirements.txt file..