Skip to content

Instantly share code, notes, and snippets.

Show Gist options
  • Save dmitry-naumenko/ce595b1eee16dde1d5e19f7e2276b966 to your computer and use it in GitHub Desktop.
Save dmitry-naumenko/ce595b1eee16dde1d5e19f7e2276b966 to your computer and use it in GitHub Desktop.
Setting up Sphinx for generating documentation from DocStrings, leveraging the Napoleon extension.

Sphinx Setup for autodoc

Sphinx is a documentation generator that is the de facto standard for Python projects. The official documentation can be a bit daunting as it includes so many options, it's hard to know where to start.

Note: This Gist was updated on 04/04/2019 to accomodate a newer version of Sphinx, as well as Python 3.7. YMMV!

This document is written with the following presuppositions:

Credits

Installation Requirements

It is assumed you already have pip installed. Also, it's a Really Good Idea (tm) to have virtualenv installed, especially virtualenvwrapper (via terminal: sudo pip3 install virtualenvwrapper), which you should learn to use.

The following can be a part of a requirements.txt file, or you can install the pieces one-at-a-time if you like (again, presumably in a Python virtualenv sandbox):

pip3 install Sphinx>=2.0.0
pip3 install sphinxcontrib-napoleon>=0.7
pip3 install sphinx-rtd-theme>=0.4.3

You should be ready to go.

Creating Your Documentation

As mentioned above, it's assumed you're already in a terminal and know how to use it.

  1. Change into your project directory. E.g., cd ~/my_repos/my_project. If this is a typical Python project, there will likely be a sub-directory in that directory that echoes your project name (where the bulk of your source lives). This is just a note for the instructions further down.

  2. Make a directory for the documentation to be generated into: mkdir docs

  3. Change into that directory: cd docs

  4. Invoke Sphinx Quick Start: sphinx-quickstart

  5. For most of the following, you'll take the defaults. For those items which are not the defaults, I'll try to highlight that as such. So, for the following:

    • > Separate source and build directories (y/n) [n]: y [enter]
    • > Project name: whatever you want the project to be called in the docs
    • > Author name(s): your name, or whoever should get credit
    • > Project release []: whatever meaningful version number you want
    • > Project language [en]: [enter]
  6. The basics have been created for you. You still have some work to do. Using the text editor of your choice, open the docs/source/conf.py and make the following changes:

    • Near the top of the file, uncomment the following lines:
    import os
    import sys
    sys.path.insert(0, os.path.abspath('.'))
    • Change that last line to: sys.path.insert(0, os.path.abspath('../..'))
    • Make sure the copyright string is what it should be (it will put your name there - change it if it's a property of your employer).
    • In the extensions block, add the following lines:
    extensions = [
        'sphinx.ext.autodoc',
        'sphinx.ext.viewcode',
        'sphinxcontrib.napoleon'
    ]
    • Find the line that says: html_theme = 'alabaster' and change it to html_theme = 'sphinx_rtd_theme'
    • Save the file and quit your editor.
  7. Generate the index .rst files: sphinx-apidoc -f -o source/ ../my_project_source where that last bit is where your actual Python code lives.

  8. Finally, generate the HTML: make html. Make sure you address any errors reported in the terminal, or the documentation will not be generated.

  9. Your files are located: docs/build/html - double-click the index.html (or, use the terminal: open build/html/index.html) to take a look.

Conclusion

There's a whole lot more power to Sphinx that can be leveraged, and this setup guide barely scratches the surface. However, for those of us just wanting to generate some basic module documentation, this should get you going.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment