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

1. 新建项目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',
]

6. 在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. 项目代码未变更

1 . 在doc下执行命令 make clean
2. 在doc下执行命令 make html（直接也行）

2. 项目代码已变更

3. 删除 doc/build 下的所有文件夹

4. 删除 doc/source 下除index.rst的所有.rst文件

5. 在doc下执行命令 sphinx-apidoc -o source …/src/

6. 在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