How to Create API Docs

I. Create API document for a Python module

Scenario

We have a python module “backend”. And suppose that scripts in the backend follows the Google Python Style Guide.

1. Modify the conf.py

in the “docs/conf.py”[1],

  1. Append a line to insert the path of module to sys.path, in this demo, it is “backend” (Line #4)
  2. Ensure the autodoc and napoleon are in the extensions (Line #7)
  3. Add a subroutine named run_apidoc (Line #9-17)
  4. Add a callback to builder-inited by app.connect (Line #23)
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
import sys, os

# append the next line to conf.py, should change "backend" to your module name
sys.path.insert(0, os.path.join(os.path.dirname(__file__),'..','backend'))

# ensure the autodoc and napoleon are in the extensions
extensions = ['sphinx.ext.autodoc', 'sphinx.ext.napoleon']

def run_apidoc(_):
    from sphinx.apidoc import main
    parentFolder = os.path.join(os.path.dirname(__file__), '..')
    cur_dir = os.path.abspath(os.path.dirname(__file__))
    sys.path.append(parentFolder)
    # change "backend" to your module name
    module = os.path.join(parentFolder,'backend')
    output_path = os.path.join(cur_dir, 'api')
    main(['-e','-f','-o', output_path, module])

def setup(app):
    # overrides for wide tables in RTD theme
    app.add_stylesheet('theme_overrides.css')
    # trigger the run_apidoc
    app.connect('builder-inited', run_apidoc)

2. Modify the index.rst

This step is optional. Suppose we hope the generated api document can be accessed from the menu on the left side, we have to modify the toctree table in the index.rst. Like this:

IMG1

3. Done

Commit the conf.py and the index.rst, then that’s done. You can see the api document at the readthedocs.org (RTD) by this URL:

http://<project-name>.readthedocs.io/en/latest/api/<module-name>.html, in this demo case, this is

http://ggeditor.readthedocs.io/en/latest/api/backend.html

II. Create API document for a Python script

Scenario

We have a python script “backend/apidocsample.py”. And suppose that this script follows the Google Python Style Guide.

Process

1. Modify the conf.py

(You can edit the conf.py by the default web-based text editor of the Github)

In the “docs/conf.py”,

  1. Append a line to insert the backend to sys.path (Line #4)
  2. Ensure the autodoc and napoleon are in the extensions (Line #7)
1
2
3
4
5
6
7
import sys, os

# append the next line to conf.py
sys.path.insert(0, os.path.join(os.path.dirname(__file__),'..','backend'))

# ensure the autodoc and napoleon are in the extensions
extensions = ['sphinx.ext.autodoc', 'sphinx.ext.napoleon']

2. Create the apidocsample.rst

Create the apidocsample.rst in the “docs”. This is simple content, you can create this file by the default web-based text editor of the Github.

apidocsample module
====================

.. automodule:: apidocsample
    :members:
    :undoc-members:
    :show-inheritance:

3. Done

Commit the conf.py and the apidocsample.rst (suppose the backend/apidocsample.py has committed already), then that’s done. You can see the api document at the RTD by this URL:

http://<project-name>.readthedocs.io/en/latest/<rst-filename>.html, in this demo case, it is http://ggeditor.readthedocs.io/en/latest/apidocsample.html

Hint

The key ideas are:

  1. The python script (apidocsample.py) should be able to import by the sphinx builder, so sys.path should be updated in the conf.py.
  2. apidocsample.rst in the docs folder is a placeholder-like file which triggers the sphinx builder to lookup apidocsample.py and collects markups from it.

Footnotes

[1]More on http://www.sphinx-doc.org/en/1.4.8/config.html#build-config