link:https://blog.csdn.net/sinat_29957455/article/details/83657029
1. 安装插件:
pip3 install sphinx
pip3 install sphinx_rtd_theme
2. 新建一个项目:
3. 使用sphinx建立API文档项目:
进入到doc目录下,输入sphinx-quickstart
命令,会输出选项。
注意看图中需要输入的内容!
项目创建后目录结构如下:
build:用来存放通过make html生成文档网页文件的目录
source:存放用于生成文档的源文件
conf.py:Sphinx的配置文件
index.rst:主文档
4. 修改source/conf.py文件中的配置信息:
模板如下,使用模板注意修改源文件位置等内容
import os
import sys
sys.path.insert(0, os.path.abspath('E:/zhibenzhu/xxx/client/python/dqlib'))
sys.path.insert(0, os.path.abspath('E:/zhibenzhu/xxx/client/python/'))
project = 'test01汉语'
copyright = '2022, test1'
author = 'test1汉语'
release = '1.0'
extensions = ['sphinx.ext.autodoc',
'sphinx.ext.doctest',
'sphinx.ext.intersphinx',
'sphinx.ext.todo',
'sphinx.ext.coverage',
'sphinx.ext.napoleon',
'sphinx.ext.autodoc',
'sphinx.ext.mathjax']
templates_path = ['_templates']
language = 'zh_CN'
exclude_patterns = []
html_theme = 'sphinx_rtd_theme'
html_static_path = ['_static']
因为我们需要从Python代码的注释中自动导出API文档,所以需要将autodoc: automatically insert docstrings from modules (y/n) [n]: y如果忘记设置,可以在conf.py中的extensions中添加’sphinx.ext.autodoc’。选项后面没有输入的,直接按回车键使用默认设置。选项后面有输入的,按照我的设置即可,如果不使用中文文档,可以在language配置中使用默认设置。
其中,sphinx.ext.napoleon可以为sphinx添加额外的扩展,如果想要将html文档转换为PDF,只需要先安装扩展,然后再此处添加即可使用。由于我们的注释代码主要同时支持googlestyle和numpy style,所以我们需要添加一个扩展来支持。
html_theme = 'sphinx_rtd_theme'
5. 将命令行切换到doc目录下,将source和src修改为自己source和src所在路径,执行命令:
sphinx-apidoc -o source ../src/
6. 清理文件(doc目录下):
./make clean
7. 生成html文件(doc目录下):
tip:再次确认conf.py和index.rst两文件的编码格式是UTF-8,否则会乱码。
./make html
8. 打开build/html/index.html
home内容,版权所有内容和创作者内容可在conf.py中修改。
各级标题内容可在index.rst中修改。
修改后./make clean ,然后生成./make html。
9. 若不想显示某些module下的文件文档,可在source目录下删除对应.rst文件即可。
本文内容由网友自发贡献,版权归原作者所有,本站不承担相应法律责任。如您发现有涉嫌抄袭侵权的内容,请联系:hwhale#tublm.com(使用前将#替换为@)