Python 文档生成-Sphinx

  • A+
所属分类:Python库介绍
摘要本文会介绍如何使用 Sphinx 来完成项目文档的生成。同时会介绍 REST 的相关语法,使用 Markdown 来写 Sphinx。

简介

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

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

 

安装 Sphinx

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

  1. pip install sphinx

 

参考资料

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

 

使用 Sphinx 快速生成文档

创建 Sphinx 项目

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

  1. sphinx-quickstart

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

1. 设置文档的根路径(回车,使用默认设置)

  1. Selected root path: .

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

  1. "source" and "build" directories within the root path.
  2. > Separate source and build directories (y/n) [n]: y

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

  1. The project name will occur in several places in the built documentation.
  2. > Project name: xxx
  3. > Author name(s): Maonan Wang
  4. > Project release []: 1.0

4. 选择文档语言(这里我们选择中文)

  1. For a list of supported codes, see
  2. https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-language.
  3. > Project language [en]: zh_CN

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

  1. sphinx-doc
  2. ├── Makefile
  3. ├── build
  4. ├── make.bat
  5. ├── _static
  6. ├── _templates
  7. ├── conf.py
  8. └── index.rst

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

  • Makefile:可以看作是一个包含指令的文件,在使用 make 命令时,可以使用这些指令来构建文档输出。
  • build:生成的文件的输出目录。
  • make.bat:Windows 用命令行。
  • _static:静态文件目录,比如图片等。
  • _templates:模板目录。
  • conf.py:存放 Sphinx 的配置,包括在 sphinx-quickstart 时选中的那些值,可以自行定义其他的值。
  • index.rst:文档项目起始文件。

 

运行 Sphinx 生成 html 文档

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

  1. .\make.bat html

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

  1. Running Sphinx v3.2.1
  2. loading translations [zh_CN]... done
  3. making output directory... done
  4. building [mo]: targets for 0 po files that are out of date
  5. building [html]: targets for 1 source files that are out of date
  6. updating environment: [new config] 1 added, 0 changed, 0 removed
  7. reading sources... [100%] index
  8. looking for now-outdated files... none found
  9. pickling environment... done
  10. checking consistency... done
  11. preparing documents... done
  12. Building prefix dict from the default dictionary ...
  13. Dumping model to file cache C:\Users\WANGMA~1\AppData\Local\Temp\jieba.cache
  14. Loading model cost 0.743 seconds.
  15. Prefix dict has been built successfully.
  16. generating indices...  genindexdone
  17. writing additional pages...  searchdone
  18. copying static files... ... done
  19. copying extra files... done
  20. dumping search index in Chinese (code: zh)... done
  21. dumping object inventory... done
  22. build succeeded.
  23. The HTML pages are in build\html.

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

Python 文档生成-Sphinx

 

reStructuredText(rst) 语法说明

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

行内样式

斜体

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

  1. *重点(emphasis)通常显示为斜体*
  2. `解释文字(interpreted text)通常显示为斜体`

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

 

粗体

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

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

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

 

等宽

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

  1. 等宽可以用来高亮一些 ``文件``,或是函数 ``function``。

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

Python 文档生成-Sphinx

 

章节标题

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

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

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

  1. 一级标题
  2. ^^^^^^^^
  3. 二级标题
  4. ---------
  5. 三级标题
  6. >>>>>>>>>
  7. 四级标题
  8. :::::::::
  9. 五级标题
  10. '''''''''
  11. 六级标题
  12. """"""""

生成的标题如下所示:

Python 文档生成-Sphinx

 

有序列表与无序列表

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

  1. - 1
  2. - 2
  3.     - 2.1
  4.     - 2.2
  5. - 3

最终的效果如下所示:

Python 文档生成-Sphinx

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

  1. 1. 枚举列表1
  2. 2. 枚举列表2
  3. #. 枚举列表3

最终的效果如下所示:

Python 文档生成-Sphinx

 

添加表格

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

列表式表格

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

  1. .. list-table:: Frozen Delights!
  2.     :widths: 15 10 30
  3.     :header-rows: 1
  4.     * - Treat
  5.       - Quantity
  6.       - Description
  7.     * - Albatross
  8.       - 2.99
  9.       - On a stick!
  10.     * - Crunchy Frog
  11.       - 1.49
  12.       - If we took the bones out, it wouldn't be crunchy, now would it?

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

Python 文档生成-Sphinx

简单表

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

  1. .. _拨码开关启动配置表:
  2. .. table:: 拨码开关启动配置表
  3. ==== ====== ========== ==== == ===
  4. 编号 名称   NAND FLASH eMMC SD USB
  5. ==== ====== ========== ==== == ===
  6. 1    MODE0  0          0    0  1
  7. 2    MODE1  1          1    1  0
  8. 3    CFG1-4 1          0    0  X
  9. 4    CFG1-5 0          1    0  X
  10. 5    CFG1-6 0          1    1  X
  11. 6    CFG1-7 1          0    0  X
  12. 7    CFG2-3 0          1    0  X
  13. 8    CFG2-5 0          0    1  X
  14. ==== ====== ========== ==== == ===
  15. 自定义名称引用 :ref:`自定义名称 <拨码开关启动配置表>` 。

最终的效果如下图所示:

Python 文档生成-Sphinx

 

添加链接

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

添加超链接

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

  1. 直接嵌入网址:
  2. `野火公司官网 <http://www.embedfire.com>`_
  3. 使用引用的方式把具体网址定义在其它地方: `野火公司官网`_
  4. .. _野火公司官网: http://www.embedfire.com

 

引用文档

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

  1. 自定义引用文字
  2. :doc:`引用本地的其它rst文档,rst后缀要省略,如about_us <../about_us>`
  3. 使用标题文字
  4. :doc:`../about_us`

 

添加图片

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

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

  1. .. image:: ../media/test.png
  2.    :align: center
  3.    :alt: test

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

  1. .. figure: ../media/test.png
  2.    :alt: test
  3.    :align: center
  4.    :caption: test

 

引用图片

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

  1. .. _引用测试:
  2. .. figure:: ./media/Snipaste_2021-07-29_11-11-44.png
  3.     :alt: 123
  4.     :align: center
  5. 这里引用上面的图像 :ref:`123 <引用测试>`

 

代码高亮

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

  1. .. code-block:: sh
  2.    :caption: test
  3.    :name: test333
  4.    :emphasize-lines: 2, 3
  5.    :linenos:
  6.    #此命令在主机执行
  7.    sudo apt install python
  8.    echo "helloworld,this is a script test!"

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

Python 文档生成-Sphinx

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

  1. Error in "code" directive:

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

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

  1. .. literalinclude:: ../../../test/test_easy_config.py
  2.    :language: python
  3.    :emphasize-lines: 5,7-12
  4.    :linenos:
  5.    :name: test_easy_config.py

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

Python 文档生成-Sphinx

 

插入数学公式

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

  1. extensions = [
  2.     'sphinx.ext.mathjax',
  3.     .....
  4. ]

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

  1. .. math::
  2.     \frac{ \sum_{t=0}^{N}f(t,k) }{N}

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

Python 文档生成-Sphinx

同时我们也支持行内公式,如下所示:

  1. 这是行内公式,:math:`\frac{ \sum_{t=0}^{N}f(t,k) }{N}`  。

最终的效果如下所示:

Python 文档生成-Sphinx

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

 

特殊提示

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

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

具体使用的时候如下所示,首先是注解(note)

  1. .. note:: This is a note admonition.
  2.  This is the second line of the first paragraph.
  3.  - The note contains all indented body elements
  4.    following.
  5.  - It includes this bullet list.
Python 文档生成-Sphinx

接着是提示(hint)重要(important)小技巧(tip)的提示,这三个的颜色都是相同的。

  1. .. hint:: This is a hint admonition.
  2. .. important:: This is a important admonition.
  3. .. tip:: This is a tip admonition.
Python 文档生成-Sphinx

接着是警告(warning与caution)注意(attention)相关的,

  1. .. warning:: This is a warning admonition.
  2. .. caution:: This is a caution admonition.
  3. .. attention:: This is a attention admonition.
Python 文档生成-Sphinx

最后是错误(error)危险(danger)相关的内容:

  1. .. error:: This is a error admonition.
  2. .. danger:: This is a danger admonition.
Python 文档生成-Sphinx

 

Sphinx 进一步说明

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

添加目录

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

  1. .. toctree::
  2.     :maxdepth: 2
  3.     usage/installation
  4.     usage/quickstart
  5.     ...

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

 

VS Code 插件-reStructuredText

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

Python 文档生成-Sphinx

 

更换主题与支持 Markdown 解析

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

  1. # support markdown
  2. $ pip3 install --upgrade recommonmark
  3. # theme
  4. $ pip3 install sphinx_rtd_theme
  5. # 暗黑系的主题
  6. $ pip3 install msmb_theme

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

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

  1. # readthedoc 风格的主题
  2. html_theme = 'sphinx_rtd_theme'
  3. # 扩展, 解析markdown
  4. extensions = [
  5.     'sphinx.ext.autodoc',
  6.     'recommonmark',
  7. ]

 

自动生成 API 文档

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

  1. sphinx-apidoc [options] -o outputdir packagedir [pathnames]

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

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

  1. import os
  2. import sys
  3. sys.path.insert(0, os.path.abspath('../../'))

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

参考资料自动生成API文档

  • 微信公众号
  • 关注微信公众号
  • weinxin
  • QQ群
  • 我们的QQ群号
  • weinxin

发表评论

:?: :razz: :sad: :evil: :!: :smile: :oops: :grin: :eek: :shock: :???: :cool: :lol: :mad: :twisted: :roll: :wink: :idea: :arrow: :neutral: :cry: :mrgreen: