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

忘是亡心i 2022-10-07 13:51 253阅读 0赞

相比于pydoc自动生成文档，sphinx的功能更强度，而且界面也更美观。  
![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzM4MDQ4NzU2_size_16_color_FFFFFF_t_70]  
下面介绍如何使用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，用浏览器打开后是如下这样的：  
![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzM4MDQ4NzU2_size_16_color_FFFFFF_t_70 1]  
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即可，此时的文档就变成下面这种主题了。  
![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzM4MDQ4NzU2_size_16_color_FFFFFF_t_70 2]

# 问题及解决方法 #

主要遇到的问题：

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上，最终达到下面的效果。  
![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzM4MDQ4NzU2_size_16_color_FFFFFF_t_70 3]  
![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzM4MDQ4NzU2_size_16_color_FFFFFF_t_70 4]  
（上图红框部分就是自动生成的内容）

# 参考资料 #

自动生成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

[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzM4MDQ4NzU2_size_16_color_FFFFFF_t_70]: /images/20221005/22cc93a885da4e2cb895c11871acae2a.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzM4MDQ4NzU2_size_16_color_FFFFFF_t_70 1]: /images/20221005/73ed3afc8b1a4628bf319867ce178ca8.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzM4MDQ4NzU2_size_16_color_FFFFFF_t_70 2]: /images/20221005/83b4b56e5b284beab01eee3237eeff00.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzM4MDQ4NzU2_size_16_color_FFFFFF_t_70 3]: /images/20221005/3368095c8dc440b1a036cc447ba5737a.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzM4MDQ4NzU2_size_16_color_FFFFFF_t_70 4]: /images/20221005/7bd4a542b8e7402ba3863ee51775fd24.png