Sphinx——自动生成Python文档

Sphinx是一个可自动生成python项目api的工具，使用起来也比较简单，只需要在项目上进行简单的配置，即可生成项目的api文档简介Sphinx是Python文档生成器，它基于reStructuredText标记语言，可自动根据项目生成HTML，PDF等格式的文档，无数著名项目的文档均用Sphinx生成，如机器学习库scikit-learn、交互式神器Jupyter Notebooksphin

你若安好我便天晴

10001人浏览 · 2021-09-28 16:02:15

你若安好我便天晴 · 2021-09-28 16:02:15 发布

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	用下划线分隔	倾向垂直，长而深的文档
Google	用缩进分隔	倾向水平，短而简单的文档

Sphinx对NumPy和Google风格的对比，英文不好可以参考中文版