使用Sphinx生成python代码文档 | SQN

LibraryPKU 2019-05-06

展开全文

今天开始使用Sphinx生成python文档。我以前用Doxygen给C代码生成文档，所以这次特意花了点时间比较Sphinx和Doxygen。读了这篇文章之后我决定使用Sphinx Comparison of Python documentation generators。

Sphinx是生成python文档最受欢迎的工具，甚至Python 3 的官方文档也是用Sphinx生成的。在本文中我将和你分享怎么使用Sphinx。

Contents [hide]

安装

你可以在这里找到sphinx在不同平台的安装方法，我只简单介绍几个比较常用的：

Debian/Ubuntu

Python2

$ apt-get install python-sphinx

Python3

$ apt-get install python3-sphinx

用pip安装

可以用于Linux, MacOS以及windows

pip install -U sphinx

用Git安装

可以用于Linux, MacOS以及windows

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

安装好Sphinx以后你可以在你的代码所在文件夹启动命令窗口并用以下命令启动sphinx:

sphinx-quickstart

比如，这里我在名叫Python的文件夹里使用该命令。文件夹中有一个python的测试代码文件。

然后我把文档的 root path命名为“ProjectDoc“, 这里你可以改成你想要的名字，但注意之后的操作要保持一致. 接下来你需要输入project的名字，作者名字，项目版本等等。大部分问题都可以直接选默认（也就是直接按回车好了）。

我没有使用默认选项的两处设置已经在下图中用红色下划线突出显示。设置完成之后，sphinx自动生成了相关文件，即下图中蓝色方框所示的文件。

现在我们找到刚生成的“ProjectDoc”文件夹。打开文件夹并找到conf文件. 我们需要在文件中取消20行到22行的注释：

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

很重要的一点是要把22行改为：

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

或者

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

我用的第二个方法，因为我的代码在conf文件的上一层文件夹。或者你也可以把这里改成你的代码的绝对地址，比如我可以改成：

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

如果这一步你把地址写错了，当生成代码文档的时候你应该会有以下报错：

sphinx ImportError: No module named 'XXXX'

现在我们转到代码所在的文件夹，并运行:

sphinx-apidoc -o ./ProjectDoc ./

这将生成rst文件并讲它们存到代码文档的根目录，这里为“ProjectDoc“. 你需要使用和在“设置”步骤中一致的根目录名称。然后我们转到代码文档的根目录，并运行：

make html

现在如果我们转到“_build\html”文件夹并打开index.html文件，你能看到与下图类似的代码文档。

由于在我的测试文件TestCode.py中代码如下，并且加入了用三引号包含起来的简短的def add(a,b) 函数介绍，因此我们可以在代码文档中看到相应的部分。在sphinx的官网和文末的参考资料中可以找到撰写代码文档的详细信息。

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

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