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即可)

Sphinx生成python文档示例图文解析插图

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

Sphinx生成python文档示例图文解析插图1

Sphinx生成python文档示例图文解析插图2

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

Sphinx生成python文档示例图文解析插图3

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

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

Sphinx生成python文档示例图文解析插图4

Sphinx生成python文档示例图文解析插图5

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

Sphinx生成python文档示例图文解析插图6

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

6.1 pip3 install sphinx_rtd_theme

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

Sphinx生成python文档示例图文解析插图7

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

Sphinx生成python文档示例图文解析插图8

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

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

Sphinx生成python文档示例图文解析插图9

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

Sphinx生成python文档示例图文解析插图10

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

Sphinx生成python文档示例图文解析插图11

Sphinx生成python文档示例图文解析插图12

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

Sphinx生成python文档示例图文解析插图13

Sphinx生成python文档示例图文解析插图14

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

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

Sphinx生成python文档示例图文解析插图15

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

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

Sphinx生成python文档示例图文解析插图16

Sphinx生成python文档示例图文解析插图17

Sphinx生成python文档示例图文解析插图18

结语

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

以上就是Sphinx生成python文档示例图文解析的详细内容,更多关于Sphinx生成python文档的资料请关注我们其它相关文章!

标签

发表评论