Sphinx生成python文档

前言

Sphinx是一款支持多种编程语言的文档生成工具，在python项目开发过程中，可以帮助开发者根据需求生成相应的说明文档，拿今天我们就基于该开源工具进行一个入门的实践。

安装

pip3 install sphinx

环境准备

1. 安装python，pycharm编辑器的电脑

2. 创建相关的项目目录，如下图所示，我们可以创建document_generate_sphinx的项目文件夹，在下面分别创建doc和src文件夹，前者用来存放sphinx工具生成的相关文档和配置文件，后者用来存放自己的项目源码文件。

3. 在src文件夹下创建demo_one.py和demo_two.py文件，并写上简单的几个类和测试代码，在doc目录下运行sphinx-quickstart，一路默认配置下来会生成如下图所示存在于doc文件夹中的文件（这其中除了要配置自己的项目名称，版本号等内容外，其他均默认或者yes即可）

3. 接下来，我们可以运行sphinx-apidoc -o ../doc ../src/ 命令将源码生成rst文件到doc的文件夹下，如下图

4. 到此，我们就可以尝试 在doc目录下 运行make html指令来生sphinx说明文档了，但是在这里发生了报错如下

从报错的内容来看分为两类，第一个是在提示我们没有发现automodule，第二个是发现modules.rst文件中没有toctree。

经过实践我们得到解决第一个问题需要在conf.py文件中添加上extensions = ["sphinx.ext.autodoc"]插件即可，解决第二个问题，需要在index.rst文件中添加上modules的文件路径，如下所示

 5. 此时，我们再去运行make clean&make html指令，可以清除之前生成的文档，生成新的文档在build或者_build文件夹中，打开_build文件夹html文件夹中的index.html文件可以发现生成的文档如下图

 6. 在实际阅读开源库的说明文档过程中会发现，目前python的很多开源文档都是统一的蓝白交替的主题，为了让自己显得更专业，可以为其替换一下目前流行的主题，在替换主题前，需要安装一下主题库，并在conf.py文件中做一个主题配置。如下

　　6.1 pip3 install sphinx_rtd_theme

　　6.2 在conf.py文件中将 html_theme = "alabaster"更换如下图，再添加上html_theme_path

 7. 重新运行make clean&make html命令，生成的新文档说明如下

 8. 至此，完成了一个简单的两个程序代码的文档生成示例，但是在实际项目中，可能还设计到其他目录下文件的添加和变更，怎样把需要展示的文件展示到文档中？类如changelog的添加，其他文件的添加。

　　比如，这里在doc目录下直接人为创建一个非py代码的说明文件，命名为changelog.rst，然后直接运行make clean&make html指令，得到了如下报错

从报错内容的提示来看，是因为changelog文件没有被放到toctree中，所以需要在index.rst文件中添加上changelog的目录，如下图所示

 9. 再次运行make clean&make html指令，编译顺利成功，但是发现打开文档目录中index后，显示特别丑，个人建议可以将其删掉，原图如下

 10. 删除掉index.rst文件中红色部分，如下左图，然后再次编译生成新的文档，可以发现没有了索引模块，显得简单干净，如下右图所示。

 11. 如果在开发过程中更改了源代码需要展示的文件，需要重新运行生成rst文件的指令 sphinx-apidoc -o ../doc ../src/

比如，为了示范，我们将原来src文件中的demo_one.py 和 demo_two.py分别更名成 animal_attack.py和dog_aonstan.py文件，并重新写了一些代码，那么就需要重新运行上述指令并删除原来的rst文件并更改modules.rst文件中的module名称，如下图

再次运行make clean&make html指令，发现编译成功，文档也更新了相关模块和内容，另外会有人说，如果需要在文档中展示的函数能够链接到源码，需要怎么做，这里很简单。

12. 文档展示函数链接源码，在conf.py文件中extensions中添加"sphinx.ext.viewcode"模块 重新生成文档如下

结语

至此，Sphinx文档生成的简单入门示例就完成啦，如果需要更深入的研究和探讨，大家可以参考sphinx的官方文档。