Sphinx——自动生成Python文档

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风格的对比，英文不好可以参考中文版

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

详情见Sphinx HTML主题

参考文献
使用sphinx自动建立API文档（一）
使用sphinx自动建立API文档（二）定制化
Sphinx 2.1.2 文档
Sphinx文档内容
Sphinx extensions
Python注释规范 — Google 开源项目风格指南
Sphinx HTML主题
PyCharm源代码文档 - 官方文档
使用sphinx快速为你python注释生成API文档
Python Docstring 风格和写法学习
sphinx-automodapi文档