Sphinx——Python生成API文档
1、简介
Sphinx是Python文档生成器，它基于reStructuredText标记语言，可自动根据项目生成HTML，PDF等格式的文档，无数著名项目的文档均用Sphinx生成，如机器学习库scikit-learn、交互式神器Jupyter Notebook
sphinx是一种基于Python的文档工具，它可以令人轻松的撰写出清晰且优美的文档，由Georg Brandl在BSD许可证下开发。新版的Python3文档就是由sphinx生成的，并且它已成为Python项目首选的文档工具，同时它对C/C++项目也有很好的支持。更多详细特性请参考spinx官方文档，本篇博客主要介绍如何快速为你的Python注释生成API文档。
2、安装sphinx
pip install sphinx
3、生成api
- 新建项目sphinx_demo，src放项目代码，doc放sphinx自动生成的文件
2.命令行进入doc目录cd doc
3.执行命令sphinx-quickstart，设置结构分离、项目名、作者名、版本号、语言（配置后面可修改）
Separate source and build directories (y/n) [n]: y
Project name: sphinx_demo
Author name(s): XerCis
Project release []: 1.0
Project language [en]: zh_CN 或 回车默认英文
4.在doc/source/conf.py指定项目代码路径
import os
import sys
sys.path.insert(0, os.path.abspath('../../src'))
5.在doc/source/conf.py修改扩展extensions，添加功能【包括注释中的文档】、【支持NumPy和Google风格】、【包括测试片段】、【链接到其他项目的文档】、【TODO项】、【文档覆盖率统计】、【通过javascript呈现数学】
extensions = ['sphinx.ext.autodoc','sphinx.ext.napoleon','sphinx.ext.doctest','sphinx.ext.intersphinx','sphinx.ext.todo','sphinx.ext.coverage','sphinx.ext.mathjax',
]
- 在source/index.rst下新增如下内容
.. toctree:::maxdepth: 2:caption: Contents:
7.命令行进入doc目录，执行生成API文档命令sphinx-apidoc -o source …/src/
8.生成HTML
(linux环境执行命令)：
make html
windows环境需要执行命令
.\make html
4、重新生成
- 项目代码未变更
1 . 在doc下执行命令 make clean
2. 在doc下执行命令 make html（直接也行）
-
项目代码已变更
-
删除 doc/build 下的所有文件夹
-
删除 doc/source 下除index.rst的所有.rst文件
-
在doc下执行命令 sphinx-apidoc -o source …/src/
-
在doc下执行命令 make html
切换主题
安装主题 pip install sphinx_rtd_theme
修改 doc/source/conf.py 的 html_theme
html_theme = ‘sphinx_rtd_theme’
注释风格
reStructuredText（PyCharm默认）
NumPy
Google（官方推荐）
风格 特点 适用
reStructuredText 用冒号分隔 PyCharm默认
NumPy 用下划线分隔 倾向垂直，长而深的文档
Google 用缩进分隔 倾向水平，短而简单的文档
Sphinx对NumPy和Google风格的对比，英文不好可以参考中文版
extensions = [‘sphinx.ext.napoleon’]
设置PyCharm Docstrings风格
File→Settings→Tools→Python Integrated Tools
在PyCharm中Ctrl+Q可很方便查看注释
光标放在函数名左端Alt+Enter→Insert documentation string stub可快速插入注释文档
项目结构
doc：Sphinx文件
src：项目源代码
doc/build：Sphinx生成文件
doc/build/doctrees：doctree文件
doc/build/html：生成的HTML文件
doc/source：Sphinx配置文件
doc/source/conf.py：Sphinx用户自定义配置文件
doc/source/index.rst：首页结构
doc/source/test.rst：test模块结构
主题大全
Sphinx的主题默认为 alabaster
参考文档：
https://blog.csdn.net/lixiaomei0623/article/details/120530642
https://www.cnblogs.com/Terrypython/p/10203332.html