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],
- Append a line to insert the path of module to sys.path, in this demo, it is “backend” (Line #4)
- Ensure the autodoc and napoleon are in the extensions (Line #7)
- Add a subroutine named run_apidoc (Line #9-17)
- 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:
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”,
- Append a line to insert the backend to sys.path (Line #4)
- 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:
- The python script (apidocsample.py) should be able to import by the sphinx builder, so sys.path should be updated in the conf.py.
- 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 |