Using Sphinx Documentation Tools

Sphinx is a tool that allows for automatic generation of documentation. It uses ReStructured Text files or Markdown to create ‘outlines’ for documents, which then get interpreted into HTML or PDF files. In fact, you’re looking at generated Sphinx documentation right now!

Note

If you copied this DefaultProject folder and ran the requirements.txt, all you have to do is change directories to the docs folder (cd docs) in the terminal, then build the output files using a command such as make html. You can make other formats of files, such as PDF, EPUB, and more!

If you are doing a fresh install of sphinx, you’ll have to do a pip install sphinx create a docs folder in your project folder (mkdir docs), change to the docs directory (cd docs) and run sphinx-quickstart.

Follow the documentation creation prompts. defaults will be shown as ‘[y]’ or ‘[n]’. Once this is done, you’ll want to build the documentation by running make html. Do this any time you want to update the documentation. Now in the build folder is the starter HTML pages.

Customization

I recommend the following edits to the conf.py file:

To have sphinx access folders outside the documentation folder, you’ll have to change the path a bit. In my setup, I have something like the following folder structure.

ProjectFolder
  • source_code

    • hello_world.py

  • docs
    • build

      • doctrees

      • html

    • conf.py

    • makefile

    • make.bat

    • index.rst

    • learning_python.rst

    • getting_started.rst

    • using_sphinx.rst

    • hello_world.rst

  • venv

  • requirements.txt

To have documentation be generated based on python code in the src directory, I need to have sphinx access the ‘source_code’ folder. To do this, we are going to do the following to change the sys.path to add the project folder. This effectively changes the scope of sphinx from ‘../../ProjectFolder/docs’ to ‘../../ProjectFolder’.

 1 # If extensions (or modules to document with autodoc) are in another directory,
 2 # add these directories to sys.path here. If the directory is relative to the
 3 # documentation root, use os.path.abspath to make it absolute, like shown here.
 4 #
 5 import os
 6 import sys
 7 if os.path.abspath('..') not in sys.path:
 8     sys.path.insert(0, os.path.abspath('..'))  # '..' moves up one folder, much like 'cd ..'
 9
10 print(sys.path)  # prints the sys.path for debugging

To automate you documentation creation, it’s useful to have some to have these the autodoc and auto-section-label extensions. I added some other things to my conf.py but these are the most important.

1 # -- General configuration ---------------------------------------------------
2
3 # Add any Sphinx extension module names here, as strings. They can be
4 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
5 # ones.
6 extensions = ['sphinx.ext.autodoc', 'sphinx.ext.autosectionlabel', 'sphinx.ext.napoleon',
7             'sphinx.ext.coverage', 'sphinx.ext.extlinks']

Finally, to further customize the look of the output files, I recommend looking into sphinx themes. Personally I choose the ‘read the docs’ theme. This was included in the pip install given in Getting Started with Python and can be customized with the following.

 1 # -- Options for HTML output -------------------------------------------------
 2
 3     # The theme to use for HTML and HTML Help pages.  See the documentation for
 4     # a list of builtin themes.
 5     #
 6     html_theme = 'sphinx_rtd_theme'
 7
 8     # Add any paths that contain custom static files (such as style sheets) here,
 9     # relative to this directory. They are copied after the builtin static files,
10     # so a file named "default.css" will overwrite the builtin "default.css".
11     html_static_path = ['_static']
12
13
14     # extra options for the read the docs theme.
15     html_theme_options = {
16         'analytics_id': 'G-XXXXXXXXXX',  # Provided by Google in your dashboard
17         'analytics_anonymize_ip': False,
18         'logo_only': False,
19         'display_version': True,
20         'prev_next_buttons_location': 'bottom',
21         'style_external_links': False,
22         'vcs_pageview_mode': '',
23         'style_nav_header_background': 'seaborn',
24         # Toc options
25         'collapse_navigation': True,
26         'sticky_navigation': True,
27         'navigation_depth': 4,
28         'includehidden': True,
29         'titles_only': False
30     }

Further Reading