Tested on:Python 2.7; Python 3
Prerequisites:Raspberry Pi with Raspbian Jessie and internet connection (see steps 1-7 in the Introduction)
0

Generating the documentation of Raspberry Pi python projects with Sphinx and Apidoc

Sphinx is a great documentation generator for Python; together with Apidoc, it is possible to generate a documentation based on Python docstrings.

Install Sphinx
To install Sphinx, enter

Download the dummy project
In the terminal, enter

The Python script myproject.py in MyProject/MyProject looks like this

with nothing but a dummy function and its docstring. The other files in the project directory are explained in the python standard project structure tutorial.

Create the documentation with Apidoc and Sphinx
Apidoc automatically parses all python files for docstrings and creates together with Sphinx a documentation out of it. Perform

This creates a directory docs/ with all documentation files. But, Sphinx needs to know where the scripts to document should be imported from. For this, open conf.py with

Below the line

add

Compile and view the documentation
After changing the scripts or the documentation files, the documentation needs to be compiled with

Now, either attach a screen, mouse and keyboard to the Raspberry Pi, open a browser (like Epiphany) and enter in the adress bar

or copy the files to a host computer with scp and watch them there.

Sphinx documentation for my_function

Sphinx documentation for my_function

Add a function description manually
Besides the automated generation with Apidoc, Sphinx uses the ReStructured Text format for documentation. Open the main documentation file index.rst with

and add above the line Contents: this example function:

After recompiling with make html, the changes are visible in the html documentation:

Sphinx documentation with manual content

Sphinx documentation with manual function description

See the excellent tutorial on sphinx-doc about more information on setting up a documentation.

Links
Sphinx Website: http://sphinx-doc.org/
ReStructured Text documentation: http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html
Sphinx Tutorial: http://sphinx-doc.org/tutorial.html
Python Docstrings: http://epydoc.sourceforge.net/docstrings.html
Standard Python project structure: http://www.knight-of-pi.org/standard-python-project-file-setup/
File transfer with SCP: http://www.knight-of-pi.org/scp-copy-linux-raspberry/

Knight of Pi

Johannes Bergs aka Knight of Pi. Diploma in Bioinformatics, some Webdesign and Python coding then. Living in the beautiful city of Vienna.

Comment

Time limit is exhausted. Please reload CAPTCHA.