使用sphinx自动生成python项目说明文档

相比于pydoc自动生成文档，sphinx的功能更强度，而且界面也更美观。

下面介绍如何使用sphinx自动生成python说明文档

如何生成说明文档

1.安装Sphinx
pip install Sphinx

2.安装好以后，在你的项目文件夹的同目录下，建立一个文件夹doc，比如：你的项目文件夹为e:\test，那么在test的同级目录下建立doc文件夹e:\doc

然后使用命令行进入doc下，输入下面的命令

sphinx-quickstart

然后回答下问题就可以了

> Separate source and build directories (y/n) [n]: y

> Project name: 
> Author name(s): 

> Project version []: 

> Project language [en]: 

3.此时会在doc下面会有一个conf.py文件，在该文件中加入如下代码：

import os
import sys
sys.path.append(os.path.relpath('../test'))

此处采用的是相对路径，就是项目相对于doc的位置，因为最初doc创建在和项目同级目录下，因此此处为'../test'。这三行代码相当于把要自动生成文档的目录导入进来，这样系统才可以找到相应的文件。然后设置自动生成文档，将conf.py中的extensions=[]改为extensions = ['sphinx.ext.autodoc',]

4.输入sphinx-apidoc -o ./source ../test，'./source'是指的保存rst文件的路径， 你的index.rst在哪个目录，那你就指定哪个目录，当然也可以设置为其他的，也是使用相对路径。'../test'就是我们要生成的html说明文档的项目路径。

5.执行make html,生成html文件，html的位置为：doc/build/html/index.html，用浏览器打开后是如下这样的：

6.上面是默认生成的主题，这里建议安装Sphinx主题。
python sphinx的主体有很多，目前很多官方说明文档，采用的是这种风格的sphinx主体包，sphinx_rtd_theme。采用如下命令进行安装：

pip install sphinx_rtd_theme

安装好以后，在conf.py中，首先导入该主题，import sphinx_rtd_theme，然后修改html_theme = 'alabaster'为

html_theme = "sphinx_rtd_theme"
html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]

7.然后重新输入make html即可，此时的文档就变成下面这种主题了。

问题及解决方法

主要遇到的问题：

WARNING: autodoc: failed to import module 'utils' from module ...; 
the following exception was raised:
No module named ...

主要原因：
就是没有把路径添加进去，最初我参考一些教程的时候，路径的设置sys.path.insert(0, os.path.abspath(’…/test’))，abspath是绝对路径，所以出现找不到模块的错误，另外就是我写的package里面，del了一些文件名，导致会有一些warning，后面把del语句去掉就好了。

小结：
对于一些官方文档，是在自动导出的文档之上，然后接着去完善文档，添加到这个上面。如下图，这个文档是在生成的html的基础上，直接对html进行调整，添加到自动生成的html上，最终达到下面的效果。


（上图红框部分就是自动生成的内容）

参考资料

自动生成Python项目文档
https://www.jianshu.com/p/d4a1347f467b
https://xiulian.blog.csdn.net/article/details/83657029

关于conf的配置可参考这个开源项目：
https://gitlab.com/hkex/emagpy/-/blob/master/doc/conf.py
这个开源项目对应的文档
https://hkex.gitlab.io/emagpy/auto_examples/nb_regolith.html

官方资料：
https://zh-sphinx-doc.readthedocs.io/en/latest/index.html
https://www.sphinx-doc.org/en/master/contents.html