Python 文档生成-Sphinx

摘要

本文会介绍如何使用 Sphinx 来完成项目文档的生成。同时会介绍 REST 的相关语法，使用 Markdown 来写 Sphinx。

简介

Sphinx 是一种文档工具，它可以令人轻松的撰写出清晰且优美的文档。使用 Sphnix 来编写文档有如下的优点：

• 使用 sphinx 编写的文档可以方便地制作 html、pdf 等格式，非常方便浏览和转换。
• sphinx 支持 rst 和 markdown 语法，方便共享及开源编辑，使用 git 也方便跟踪。
• 由于 rst 语法比 markdown 语法更强大和方便，我们主要采用 rst 语法编写文档， linux内核源码文档也是使用rst格式编写的。

 

安装 Sphinx

Sphinx 作为一个 Python 的第三方库，可以直接使用 pip 进行安装。

 

参考资料

下面第二和第三个资料，非常的详细，可以进行参考。

• 用Sphinx快速制作文档，知乎专栏，排版还是挺好的
• [野火]sphinx文档规范与模版,非常详细的 sphnix 的文档（这里没有介绍 API 文档的生成）
• [博客园]reStructuredText(rst)快速入门语法说明，非常详细的介绍了 rst 的语法
• 用Sphinx编写API文档，这里会有介绍 API 文档的生成

 

使用 Sphinx 快速生成文档

创建 Sphinx 项目

首先进入想要创建文档的文件夹，运行下列命令快速生成 Sphinx 项目：

接下来会让我们选择一些配置：

1. 设置文档的根路径（回车，使用默认设置）

2. 是否分离source和build目录（输入y,选择分离，方便管理）

3. 输入项目名称、作者和版本号

4. 选择文档语言（这里我们选择中文）

完成这些设置之后会完成目录的初始化，目录的文件结构如下：

我们对上面的文件进行简单的解释：

 

运行 Sphinx 生成 html 文档

在 Windows 下运行下面的命令，可以完成默认的文档的生成

如果在 ubuntu 下，可以直接使用 make html 即可。出现下面的提示则表示生成成功，我们可以在 build/html 中找到生成的文件。

直接打开 build/html/index.html 可以看到默认生成的页面。

 

reStructuredText(rst) 语法说明

我们通过编辑 rst 文件来对文档添加内容。这里我们首先介绍 rst 文件的语法，更加方便我们后面进行文档的编写，这篇内容主要参考自，reStructuredText(rst)快速入门语法说明

行内样式

斜体

重点、解释文字，使用「单个星号」来表示「斜体」。

重点(emphasis)通常显示为斜体

 

粗体

与 Markdown 相似，使用「两个星号」表示加粗。

重点强调(strong emphasis)通常显示为粗体

 

等宽

使用「两个`」来表示等宽。说等宽可能不是很明白，我们直接看一下最终的效果：

需要注意的是，使用时候需要与前面内容有一个「空格」。最终的效果如下：

 

章节标题

章节头部由下线（也可有上线）和包含标点的标题组合创建, 其中下线要至少等于标准文本的长度。可以表示标题的符号有 =、-、`、:、'、"、~、^、_ 、* 、+、 #、<、> 。

对于相同的符号，有上标是一级标题，没有上标是二级标题。标题最多分六级，可以自由组合使用。

全加上上标或者是全不加上标，使用不同的 6 个符号的标题依次排列，则会依次生成的标题为H1-H6。例如下面使用 6 个不同的符号，会生成六种标题：

生成的标题如下所示：

 

有序列表与无序列表

符号列表可以使用 -、 *、+ 来表示（我自己个人会更加喜欢使用 - 来表示列表，这样可以和 Markdown 的语法是相同的）。下面是一个有缩进的列表。

最终的效果如下所示：

当然也可以使用数字关键词来生成枚举列表。可以使用阿拉伯数字（1、2、3、4、5 ...），字母（A-Z，a-z），罗马数字（I, II, ...）来完成枚举列表。同时枚举列表可以结合「#」来自动生成枚举的序号，如下所示：

最终的效果如下所示：

 

添加表格

有多种添加表格的方式，这里推荐「列表式」和「简单表」这两种表格，修改起来会比较方便。

列表式表格

下面首先介绍「列表式」表格的语法：

这里的最终的效果如下所示：

简单表

接着看一下简单表的使用，就是用横线表把表格勾勒出来。下面是一个简单的例子，包含了如何引用表格：

最终的效果如下图所示：

 

添加链接

这一部分主要参考自，Sphnix 文档添加超链接。

添加超链接

有下面两种插入超链接的方式：

 

引用文档

我们需要在一个文档中引用另外一个文档，可以使用下面的方式，注意 rst 的后缀需要省略。

 

添加图片

使用 image 或是 figure 命令来进行图片的插入。无特殊情况的话我们图片要求使用居中方式显示， 还需要添加“alt”选项指定图片的描述（类似doc中的题注），以便图片加载失败时显示文字。

使用 image 命令的方式如下所示：

使用 figure 命令的方式如下所示：

 

引用图片

我们在图像定义的上面写引用的标签，这里是 引用测试，注意前面有一个短横。后面引用的时候，使用 :ref:自定义名称 <引用测试> 即可。

 

代码高亮

我们使用 code-block 来进行代码高亮。例如，我们希望对 shell 进行高亮处理。下面「emphasize-lines」表示对某些进行高亮，「linenos」表示最终包含行号。

上面高亮的最终结果如下所示：

注意，这里使用 code 关键词也是可以进行代码的高亮，但是会不支持 linenos 这个功能，会出现如下的报错：

这里还是使用 code-block 进行代码的高亮会比较好。参考资料，Error in "code-block" directive: unknown option: "linenos".

我们也可以直接插入代码文件。下面是插入 python 代码，并对插入的代码进行高亮的例子。当对连续的行进行高亮的时候，可以使用短横：

上面高亮的最终结果如下所示：

 

插入数学公式

我们也是可以在 rst 中插入数学公式，与在 LaTeX 中数学公式类似。关于插入数学公式详细的说明可以参考链接，reStructuredText 高级语法功能。我们首先需要在 conf.py 文件中设置 extensions，在这里添加 sphinx.ext.mathjax：

首先也是支持独立的公式段，如下所示：

这一部分最终的效果如下所示：

同时我们也支持行内公式，如下所示：

最终的效果如下所示：

这一部分参考自，Math in reStructuredText with LaTeX

 

特殊提示

Sphinx 支持一些特殊的提示，例如「重要」、「提示」、「警告」等，这些特殊的提示可以高亮一些内容，使关键内容更加显眼。常见的特殊提示如下所示：

• attention（注意）
• caution（警告）
• danger（危险）
• error（错误）
• hint（提示）
• important（重要）
• note（注解）
• tip（小技巧）
• warning（警告）

具体使用的时候如下所示，首先是注解（note）：

接着是提示（hint）、重要（important）、小技巧（tip）的提示，这三个的颜色都是相同的。

接着是警告（warning与caution）和注意（attention）相关的，

最后是错误（error）和危险（danger）相关的内容：

 

Sphinx 进一步说明

上面我们介绍了如何使用 Sphinx 快速的生成默认的文档。同时也介绍了 reStructuredText(rst) 的相关语法，了解了这些语法之后我们就可以自己编辑文档了。下面我们对 Sphinx 进行进一步的说明，例如如何生成 API 文档，如何使用 Markdown 编辑等。

添加目录

首先最重要的就是如何生成首页的目录。一般情况下，index.rst 是项目的主文档，我们可以在其中的toctree 里添加其它 rst 文件。如下所示：

那么此时，在 usage 文件夹下，就需要有 installation.rst 和 qucikstart.rst 这两个文件。每个文件中都可以有 toctree，按上面的格式，去引用其他的文件。

 

VS Code 插件-reStructuredText

为了更好的编辑文档，这里推荐使用 VS Code 中 reStructuredText 的这个插件。可以帮助我们可视化的编辑 rst 文档。可视化的效果还是很不错的，如下所示：

 

更换主题与支持 Markdown 解析

为了能够更换主题和支持 Markdown 解析我们首先安装扩展。

使用 Sphinx 默认生成的风格为 alabaster，我们这里修改为 ReadTheDocs 的风格 ，即sphinx_rtd_theme。

安装完毕之后我们修改 conf.py 文件的内容，该文件路径为 source/conf.py。按照以下的格式进行修改即可。

 

自动生成 API 文档

我们需要使用 sphinx-apidoc 来代码文件生成对应rst文件，使用方法如下：

我们只需要在 outputdir 的位置指定输出的文件夹路径，在 packagedir 指定我们要生成的包的路径即可。这样会在指定的位置生成 rst 文件。

除此之外我们还需要对 conf.py 进行修改，需要将 package 的路径加入，如下所示：

如果你还想添加查看源代码的功能，需要在extension里加入 'sphinx.ext.viewcode',即可。做完这些之后，我们运行 make html 即可生成指定的 API 文档。

参考资料，自动生成API文档