（中文版请点击此处）

 

Today I started to use Sphinx for the generation of python documentation. I spent some time to choose between Sphinx and Doxygen, which I used to use for C code. After reading the article

Comparison of Python documentation generators, I decided to turn to Sphinx.

Sphinx is most recommended for generating python code documentation. Even the Python 3 official documentation was generated by Sphinx. I will give you a brief introduction on how to use it.

Installation

The detailed information regarding installation of Sphinx on different platforms could be found here. Here I just listed some commonly used options,

 

Debian/Ubuntu

For python2

$ apt-get install python-sphinx

or for python3

$ apt-get install python3-sphinx

 

Installation with pip

For Linux, MacOS as well as for windows

pip install -U sphinx

 

Installation via Git

For Linux, MacOS as well as for windows

$ git clone https://github.com/sphinx-doc/sphinx
$ cd sphinx
$ pip install .

 

Setup and Use

start sphinx

When Sphinx is installed, you can go to your code folder and start sphinx by typing in the command window:

sphinx-quickstart

For example, here I run the command in the location of my code folder, which names “Python” and has a test code file.

 

Settings

Then I named the root path for the documentation as “ProjectDoc“, you can name it as you wish. In the rest parts of the settings, you need to give the project name, author names, project version and so on. For the most of the other questions, you can use the default option, i.e. you just have to press Enter.

The two options that I chose not to use default options were marked with the red underline. When you finish all the settings, the needed files are automatically generated, which is showed in the blue frame in the picture.

 

Modification of conf file

Now we can find a folder names “ProjectDoc” is generated. Let us open it and find the conf file. We need to edit the conf file and uncomment the lines 20 to 22, which are

import os
import sys
sys.path.insert(0, os.path.abspath('.'))

 

Very important is to change the 22nd line as below,

sys.path.insert(0, os.path.abspath('../..'))

or as

sys.path.insert(0, os.path.abspath('..'))

The second option works for me. There is also another option, i.e. you can use the absolute path of your code folder. As for me, I can use

sys.path.insert(0, os.path.abspath('D:\GitLocal\OtherCodes\Python'))

If you made mistake at this step, probably you will have the following problem later when you generate the documentation:

sphinx ImportError: No module named 'XXXX'

 

Generate rst files and Documentation

Now let’s first go to the code folder and run:

sphinx-apidoc -o ./ProjectDoc ./

This will generate the rst files and save them to your root path for the documentation, here is “ProjectDoc“. You need to use the one you have set in the first step of “settings”

Then we go to the root path of the documentation and run:

make html

 

Now when you go to the folder “_build\html” and open the index.html file, you will find the documentation showed similar to the next picture.

Since in my TestCode.py file I have the following code and have a simple documentation for the function,def add(a,b) we can find the corresponding in the picture. More information regarding how to write the documentation could be found on sphinx official website, or in the references of this article.

def add(a,b):
    """ADD a and b"""
    return a + b

a=3
b=8
c=add(a,b)
print(c)

 

References

1. SPHINX website
2. Comparison of Python documentation generators Installing Sphinx
3. Sphinx将python代码注释生成文档
4. reStructuredText 简介
5. Jonga Documentation
6. sphinx-pyreverse 0.0.12
7. Python Call Graph
8. Creating diagrams in Sphinx
9. Sphinx autodoc: automated API documentation