Sphinx入门——快速生成Python文档

简介

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

在这里插入图片描述

安装

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

在这里插入图片描述

  1. doc/source/conf.py指定项目代码路径
import os
import sys
sys.path.insert(0, os.path.abspath('../../src'))
  1. 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',
]
  1. 命令行进入doc目录,执行生成API文档命令sphinx-apidoc -o source ../src/
    在这里插入图片描述
  2. 生成HTMLmake html
  3. 打开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

切换主题

  1. 安装主题pip install sphinx_rtd_theme
  2. 修改doc/source/conf.pyhtml_theme
html_theme = 'sphinx_rtd_theme'
  1. 重新生成
    在这里插入图片描述

注释风格

  1. reStructuredTextPyCharm默认
  2. NumPy
  3. Google(官方推荐)
风格特点适用
reStructuredText用冒号分隔PyCharm默认
NumPy用下划线分隔倾向垂直,长而深的文档
Google用缩进分隔倾向水平,短而简单的文档

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

extensions = ['sphinx.ext.napoleon']

设置PyCharm Docstrings风格

FileSettingsToolsPython Integrated Tools
在这里插入图片描述
在PyCharm中Ctrl+Q可很方便查看注释
在这里插入图片描述
光标放在函数名左端Alt+EnterInsert 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主题

参考文献

  1. 使用sphinx自动建立API文档(一)
  2. 使用sphinx自动建立API文档(二)定制化
  3. Sphinx 2.1.2 文档
  4. Sphinx文档内容
  5. Sphinx extensions
  6. Python注释规范 — Google 开源项目风格指南
  7. Sphinx HTML主题
  8. PyCharm源代码文档 - 官方文档
  9. 使用sphinx快速为你python注释生成API文档
  10. Python Docstring 风格和写法学习
  11. sphinx-automodapi文档
相关推荐
©️2020 CSDN 皮肤主题: 编程工作室 设计师:CSDN官方博客 返回首页