简介

Sphinx是Python文档生成器，它基于reStructuredText标记语言，可自动根据项目生成HTML，PDF等格式的文档，无数著名项目的文档均用Sphinx生成，如机器学习库scikit-learn、交互式神器Jupyter Notebook

在这里插入图片描述

安装

pip install sphinx

初试

新建项目sphinx_demo，src放项目代码，doc放sphinx自动生成的文件
项目代码

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

命令行进入doc目录cd doc
执行命令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 或 回车默认英文

在这里插入图片描述

在doc/source/conf.py指定项目代码路径

import os
import sys
sys.path.insert(0, os.path.abspath('../../src'))

在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',
]

命令行进入doc目录，执行生成API文档命令sphinx-apidoc -o source ../src/
生成HTMLmake html
打开build/html/reStructredText.html

重新生成

1. 项目代码未变更

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

2. 项目代码已变更

删除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可快速插入注释文档