Sphinx

Sphinx is a popular tool for generating documentation from docstrings.

Setup

To be able to generate documentation using Sphinx, follow the steps below.

  1. If you haven't already, install Sphinx:
    $ apt install python3-sphinx
  2. Create a directory for the documentation:
    $ mkdir docs && cd docs
  3. Use the quickstart tool to initialize the config:
    $ sphinx-quickstart
    Default values can be used for all the questions except:
    > autodoc: automatically insert docstrings from modules (y/n) [n]: y
    > Create Windows command file? (y/n) [y]: n
  4. $ sphinx-apidoc -o source/ MODULE_PATH
  5. Uncomment the line:
    sys.path.insert(0, os.path.abspath('.'))
    and add the following line after:
    sys.path.insert(0, os.path.abspath('../'))
  6. Run:
    make html
    to generate the documentation. It can be found through _build/html/index.html.

For more thorough instructions see An idiot’s guide to Python documentation with Sphinx and ReadTheDocs.

Numpy style

Numpy style is a docstring style that has an extension for Sphinx. Apart from Numpy, it seems to be fairly well used [1][2]. To enable the extension, add 'sphinx.ext.napoleon' to the list extensions in the configuration file.

Troubleshooting

ImportError: No module named [...]

If you move around files and get error like:

ImportError: No module named [...]

you may need to update the files in source/ by running $ sphinx-apidoc -o source/ MODULE_PATH. Note that this won't change any existing files, so you may need to empty source/ first. This also happens if you use venv and have installed things with pip. Sphinx uses the "outside" (non-venv) version of Pyhton to run (even when a virtual environment is active). This can be solved by adding the following to the start of conf.py (among the other path lines):

sys.path.insert(0, os.path.abspath('../lib/python3.5/site-packages/'))

Pywikibot

Importing Pywikibot modules will cause errors when running make, because there is no user-config.py in docs/. To fix this, run PYWIKIBOT2_NO_USER_CONFIG=1 make html.