引言
我在本科期间需要完成一个python项目,现在到了最后的一步了,为了让我写的程序能够被他人继续使用下去,为自己写的程序添加文本说明是相当有必要的。我采用Sphinx自动生成文档,写这个博客的目的其一是记录自己的操作,万一哪一天我还能用得上呢,其二是因为我无法根据他人写的博客实现我的目的(无法重复出来),故记录于此以便有和我共同需求的小伙伴们使用。本文主要参考博客为这个.
安装Sphinx
不管你是什么系统,请先安装conda,安装conda的教程网上很多,如果我有时间也会尝试写一个,虽然可以不通过conda安装sphinx,但conda确实是一个管理软件包的好东西,而且非常方便,如果是经常要用到python编程的话,conda多半都是必不可少的,我也相信能够看到这个博客的人多半也安装了conda。当你有conda的时候,进入一个你想安装sphinx的虚拟环境(关于虚拟环境的博客以后再写吧,网上也有不少介绍),键入:
1 | conda install sphinx |
稍等片刻就安装完成了。
文件夹说明
以下是我的文件夹目录:
1 | . |
其中Doc/是我们希望生成文档的位置,bicks/是一个python程序包(这就是我和网上教程对不上的关键,网上的教程只适用于普通的python脚本,不能用于程序包,但一般希望自己的程序能够有个说明文档的时候,这个程序往往对应着一个包),我们就是要生成这个程序包的相关文档。
自动生成文档
进入Doc/,在该文件夹打开终端(windows系统尝试用git bash),切换到安装sphinx的虚拟环境,然后输入:
1 | sphinx-quickstart |
开始初始化,根据提示输入相应的信息即可完成初始化。完成后,你的目录应该是类似这样的:
1 | . |
我们需要简单的配置一下位于./Doc/source/conf.py的conf.py文件,将被注释的
1 | # import os |
修改为
1 | import os |
其中最后一栏就是指定python包所在的文件夹(注意:是python包所在的文件夹,不是python包本身),然后将配置文件(即conf.py)中的extensions修改为:
1 | extensions = [ |
只有做了这样的修改,Sphinx才能够认识你的注释,然后保存退出。在Doc/处打开终端,键入sphinx-apidoc -o source ../bicks这是生成API文档的命令,后面的../bicks是python包的位置,换成相应的命名就OK了。最后使用命令:
1 | make html |
这个时候,文件夹的结构应当变为类似这样的结构:
1 | . |
注意到bulid文件夹中多了不少东西,./doc/bulid/html/中就有我们生成的API文档,点击这个文件夹中的bicks.html即可浏览API文档(bicks是python包的名字,换成你自己的)。以后有时间了再写一下模板的事情吧。