Developer guidelines/Python documentation

Sphinx

Sphinx is a popular tool for generating documentation from docstrings.

Setup

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

0. If you haven't already, install Sphinx:
   $ apt install python3-sphinx
1. Create a directory for the documentation:
   $ mkdir docs && cd docs
2. 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
3. $ sphinx-apidoc -o source/ MODULE_PATH
4. Uncomment the line:
   sys.path.insert(0, os.path.abspath('.'))
   and add the following line after:
   sys.path.insert(0, os.path.abspath('../'))
5. 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.