Sphinx是一个可自动生成python项目api的工具，使用起来也比较简单，只需要在项目上进行简单的配置，即可生成项目的api文档
简介
Sphinx是Python文档生成器，它基于reStructuredText标记语言，可自动根据项目生成HTML，PDF等格式的文档，无数著名项目的文档均用Sphinx生成，如机器学习库scikit-learn、交互式神器Jupyter Notebook
sphinx是一种基于Python的文档工具，它可以令人轻松的撰写出清晰且优美的文档，由Georg Brandl在BSD许可证下开发。新版的Python3文档就是由sphinx生成的，并且它已成为Python项目首选的文档工具，同时它对C/C++项目也有很好的支持。更多详细特性请参考spinx官方文档，本篇博客主要介绍如何快速为你的Python注释生成API文档。
环境
需要安装python
安装sphinx
安装
pip install sphinx
初试
1. 新建项目sphinx_demo，src放项目代码，doc放sphinx自动生成的文件
2. 项目代码
google_style.py
# -*- coding: utf-8 -*-
'''Google注释风格
详情见 `Google注释风格指南`_
.. _Google注释风格指南:
https://google.github.io/styleguide/pyguide.html
'''
class GoogleStyle:
'''Google注释风格
用 ``缩进`` 分隔，
适用于倾向水平，短而简单的文档
Attributes:
dividend (int or float): 被除数
name (:obj:`str`, optional): 该类的命名
'''
def __init__(self, dividend, name='GoogleStyle'):
'''初始化'''
self.dividend = dividend
self.name = name
def divide(self, divisor):
'''除法
Google注释风格的函数，
类型主要有Args、Returns、Raises、Examples
Args:
divisor (int):除数
Returns:
除法结果
Raises:
ZeroDivisionError: division by zero
Examples:
>>> google = GoogleStyle(divisor=10)
>>> google.divide(10)
1.0
References:
除法_百度百科 https://baike.baidu.com/item/%E9%99%A4%E6%B3%95/6280598
'''
try:
return self.dividend / divisor
except ZeroDivisionError as e:
return e
numpy.py
# -*- coding: utf-8 -*-
"""NumPy注释风格
详情见 `NumPy注释风格指南`_
.. _NumPy注释风格指南:
https://numpydoc.readthedocs.io/en/latest/format.html#docstring-standard
"""
class NumpyStyle:
'''Numpy注释风格
用 ``下划线`` 分隔，
适用于倾向垂直，长而深的文档
Attributes
----------
multiplicand : int
被乘数
name : :obj:`str`, optional
该类的命名
'''
def __init__(self, multiplicand, name='NumpyStyle'):
'''初始化'''
self.multiplicand = multiplicand
self.name = name
def multiply(self, multiplicator):
'''乘法
Numpy注释风格的函数，
类型主要有Parameters、Returns
Parameters
----------
multiplicator :
乘数
Returns
-------
int
乘法结果
Examples
--------
>>> numpy = NumpyStyle(multiplicand=10)
>>> numpy.multiply(10)
100
'''
try:
if isinstance(multiplicator, str):
raise TypeError('Division by str')
else:
return self.multiplicand * multiplicator
except TypeError as e:
return e
reStructredText.py
# -*- coding: utf-8 -*-
class ReStructuredTextStyle:
'''reStructuredText风格
用 ``冒号`` 分隔，
PyCharm默认风格
:arg augend: 被加数
:type augend: int
'''
def __init__(self, augend, name='ReStructuredTextStyle'):
'''初始化'''
self.augend = augend
self.name = name
def add(self, addend):
'''加法
reStructuredText风格的函数，
类型主要有param、type、return、rtype、exception
:param addend: 被加数
:type addend: int
:returns: 加法结果
:rtype: :obj:`int` or :obj:`str`
:exception TypeError: Addition by str
>>> reStructredText = ReStructuredTextStyle(augend=10)
>>> reStructredText.add(10)
20
'''
try:
if isinstance(addend, str):
raise TypeError('Addition by str')
else:
return self.augend + addend
except TypeError as e:
return e
3. 命令行进入doc目录cd doc
4. 执行命令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 或 回车默认英文
5. 在doc/source/conf.py指定项目代码路径
import os
import sys
sys.path.insert(0, os.path.abspath('../../src'))
6. 在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',
]
7. 命令行进入doc目录，执行生成API文档命令sphinx-apidoc -o source ../src/
8.生成HTML
(linux环境执行命令)：
make html
windows环境需要执行命令
.\make html
9.打开build/html/reStructredText.html
重新生成
1. 项目代码未变更
1 . 在doc下执行命令 make clean
2. 在doc下执行命令 make html（直接也行）
2. 项目代码已变更
1. 删除 doc/build 下的所有文件夹
2. 删除 doc/source 下除index.rst的所有.rst文件
3. 在doc下执行命令 sphinx-apidoc -o source ../src/
4. 在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 | 用下划线分隔 | 倾向垂直，长而深的文档 |
| 用缩进分隔 | 倾向水平，短而简单的文档 |
Sphinx对NumPy和Google风格的对比，英文不好可以参考中文版
extensions = ['sphinx.ext.napoleon']
File→Settings→Tools→Python Integrated Tools
在PyCharm中Ctrl+Q可很方便查看注释
光标放在函数名左端Alt+Enter→Insert documentation string stub可快速插入注释文档
项目结构
Sphinx的主题默认为 alabaster
参考文献
使用sphinx自动建立API文档（一）
使用sphinx自动建立API文档（二）定制化
Sphinx 2.1.2 文档
Sphinx文档内容
Sphinx extensions
Python注释规范 — Google 开源项目风格指南
Sphinx HTML主题
PyCharm源代码文档 - 官方文档
使用sphinx快速为你python注释生成API文档
Python Docstring 风格和写法学习
sphinx-automodapi文档