Setting up Sphinx for generating documentation from DocStrings, leveraging the Napoleon extension.

Sphinx_Setup_for_autodoc.md

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:

• You want to leverage the DocStrings in your Python code.
• You'd rather write your DocStrings in Google-style instead of a more awkward reStructuredText format for calling documentation.
• You like the ReadTheDocs CSS style.
• You don't want to have to learn about all the possible paths you can take with Sphinx.
• You are comfortable with a terminal (a flavor of *nix is assumed, whether it's Linux or macOS); if you're using Windoze you'll have to interpolate my instructions.

Credits

• Author: Greg Meece (alternately, my LinkedIn profile)
• Sphinx documentation - way more power than I've learned how to use yet!
• Napoleon extension - makes writing args, returns, etc. so much easier!
• Sphinx for Python documentation - the best documentation I found for my purposes (used as guide for this document).

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.

Great guide! Just a small point: Since Sphinx 1.3, Napoleon has come packaged with Sphinx as sphinx.ext.napoleon.