martes, 31 de enero de 2017

Simple example of Sphinx apidoc

I created a gihub repo with a really simple example of how to use the sphinx-apidoc program to automatically generate documentation of a python package.
You can find the repo here
The following text is just a copy-paste of the README file of the mentioned repo
To try this example just clone the package
git clone
And then go into the created folder
cd sphinx_apidoc_example
And follow the next steps.
In order to create the documentation first it is necessary to generate all the configuration files. The easiest way is just to run the following script.
sphinx-apidoc -o docs -E -H PackageName -A "Author Name" -V 0.1 -f -F package/
  • -o Directory to place the output files.
  • -E Put each module file in its own page.
  • -H Project name to put into the configuration.
  • -A Author name(s) to put into the configuration.
  • -V Project version.
  • -f Usually, apidoc does not overwrite files, unless this option is given.
  • -F If given, a full Sphinx project is generated using sphinx-quickstart.
Then you need to modify the file docs/ by adding the path to the root folder with the package.
import os
import sys
sys.path.insert(0, os.path.abspath('../'))
Now it is possible to generate the documentation by going to the docs folder and running the sphinx code. The easiest way is
cd docs
make html
It will generate an index.html in docs/_build/html/index.html and it should look something similar to this index.html

No hay comentarios:

Publicar un comentario