文档工具的王者Sphinx

Sphinx

https://www.sphinx.org.cn/

Sphinx是一个工具，可以轻松创建由Georg Brandl编写并根据BSD许可证授权的智能和美观文档

它最初是为Python文档创建的，它具有出色的工具，可用于各种语言的软件项目文档。 当然，这个站点也是使用reStructuredText源创建的

• 输出格式: HTML（包括Windows HTML帮助），LaTeX（适用于可打印的PDF版本），ePub，Texinfo，手册页，纯文本
• 广泛的交叉引用: 语义标记和功能，类，引用，词汇表术语和类似信息的自动链接
• 分层结构: 轻松定义文档树，自动链接到平级，上级和下级
• 自动索引: 一般索引以及特定于语言的模块索引
• 代码处理: 使用Pygments荧光笔自动突出显示
• 扩展: 自动测试代码片段，包含Python模块（API文档）中的文档字符串等
• 贡献的扩展: 用户在第二个存储库中贡献了50多个扩展;其中大多数可以从PyPI安装

入门

https://www.sphinx.org.cn/usage/quickstart.html

例子

https://github.com/plasmatech8/Python-Sphinx-Demo

reStructuredText

https://zh-sphinx-doc.readthedocs.io/en/latest/rest.html

docutils.sourceforge.net/rst.html

https://www.jianshu.com/p/1885d5570b37

reStructuredText 是扩展名为.rst的纯文本文件，含义为"重新构建的文本"，也被简称为：RST或reST；是Python编程语言的Docutils项目的一部分，Python Doc-SIG (Documentation Special Interest Group)。该项目类似于Java的JavaDoc或Perl的POD项目。 Docutils 能够从Python程序中提取注释和信息，格式化成程序文档。

.rst 文件是轻量级标记语言的一种，被设计为容易阅读和编写的纯文本，并且可以借助Docutils这样的程序进行文档处理，也可以转换为HTML或PDF等多种格式，或由Sphinx-Doc这样的程序转换为LaTex、man等更多格式。

Sphinx标记的组成

http://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html

Sphinx 在 standard reST markup 基础上新增了许多指令和文本解释角色. 本章节是这些特性的参考资料.

• 目录树
  • 预留名子
• 段落级别的标记
• 目录表格标记
• 术语
• 语法产品的显示
• 展示示例代码
  • 行号
  • 包含
• 内联标记
  • 交叉索引的语法
    • 交叉索引的对象
    • 交叉索引的位置
    • 参考文档
    • 可下载的参考文件
    • 其他有趣的交叉索引
  • 其他语义标记
  • 替换
• 未分类标记
  • 文件范围的元数据
  • 元信息标记
  • 索引生成标记
  • 包含基于标签的内容
  • Tables

docstrings

https://www.datacamp.com/community/tutorials/docstrings-python#fifth-sub

Sphinx Style

Sphinx is the easy and traditional style, verbose and was initially created specifically for the Python Documentation. Sphinx uses a reStructuredText which is similar in usage to Markdown.

class Vehicle(object):
    '''
    The Vehicle object contains lots of vehicles
    :param arg: The arg is used for ...
    :type arg: str
    :param `*args`: The variable arguments are used for ...
    :param `**kwargs`: The keyword arguments are used for ...
    :ivar arg: This is where we store arg
    :vartype arg: str
    '''

    def __init__(self, arg, *args, **kwargs):
        self.arg = arg

    def cars(self, distance, destination):
        '''We can't travel a certain distance in vehicles without fuels, so here's the fuels

        :param distance: The amount of distance traveled
        :type amount: int
        :param bool destinationReached: Should the fuels be refilled to cover required distance?
        :raises: :class:`RuntimeError`: Out of fuel

        :returns: A Car mileage
        :rtype: Cars
        '''
        pass

Sphinx uses the "keyword(reserved word)", most of the programming language does. But it is called specifically "role" in Sphinx. In the above code, Sphinx has the "param" as a role, and "type" is a role which is the Sphinx data type for "param". "type" role is optional, but "param" is mandatory. The return roles document the returned object. It is different from the param role. The return role is not dependent on the rtype and a vice-versa. The rtype is the type of object returned from the given function.

https://thomas-cokelaer.info/tutorials/sphinx/docstring_python.html

"""This module illustrates how to write your docstring in OpenAlea
and other projects related to OpenAlea."""

__license__ = "Cecill-C"
__revision__ = " $Id: actor.py 1586 2009-01-30 15:56:25Z cokelaer $ "
__docformat__ = 'reStructuredText'

class MainClass1(object):
    """This class docstring shows how to use sphinx and rst syntax

    The first line is brief explanation, which may be completed with
    a longer one. For instance to discuss about its methods. The only
    method here is :func:`function1`'s. The main idea is to document
    the class and methods's arguments with 

    - **parameters**, **types**, **return** and **return types**::

          :param arg1: description
          :param arg2: description
          :type arg1: type description
          :type arg1: type description
          :return: return description
          :rtype: the return type description

    - and to provide sections such as **Example** using the double commas syntax::

          :Example:

          followed by a blank line !

      which appears as follow:

      :Example:

      followed by a blank line

    - Finally special sections such as **See Also**, **Warnings**, **Notes**
      use the sphinx syntax (*paragraph directives*)::

          .. seealso:: blabla
          .. warnings also:: blabla
          .. note:: blabla
          .. todo:: blabla

    .. note::
        There are many other Info fields but they may be redundant:
            * param, parameter, arg, argument, key, keyword: Description of a
              parameter.
            * type: Type of a parameter.
            * raises, raise, except, exception: That (and when) a specific
              exception is raised.
            * var, ivar, cvar: Description of a variable.
            * returns, return: Description of the return value.
            * rtype: Return type.

    .. note::
        There are many other directives such as versionadded, versionchanged,
        rubric, centered, ... See the sphinx documentation for more details.

    Here below is the results of the :func:`function1` docstring.

    """

    def function1(self, arg1, arg2, arg3):
        """returns (arg1 / arg2) + arg3

        This is a longer explanation, which may include math with latex syntax
        :math:`\\alpha`.
        Then, you need to provide optional subsection in this order (just to be
        consistent and have a uniform documentation. Nothing prevent you to
        switch the order):

          - parameters using ``:param <name>: <description>``
          - type of the parameters ``:type <name>: <description>``
          - returns using ``:returns: <description>``
          - examples (doctest)
          - seealso using ``.. seealso:: text``
          - notes using ``.. note:: text``
          - warning using ``.. warning:: text``
          - todo ``.. todo:: text``

        **Advantages**:
         - Uses sphinx markups, which will certainly be improved in future
           version
         - Nice HTML output with the See Also, Note, Warnings directives

        **Drawbacks**:
         - Just looking at the docstring, the parameter, type and  return
           sections do not appear nicely

        :param arg1: the first value
        :param arg2: the first value
        :param arg3: the first value
        :type arg1: int, float,...
        :type arg2: int, float,...
        :type arg3: int, float,...
        :returns: arg1/arg2 +arg3
        :rtype: int, float

        :Example:

        >>> import template
        >>> a = template.MainClass1()
        >>> a.function1(1,1,1)
        2

        .. note:: can be useful to emphasize
            important feature
        .. seealso:: :class:`MainClass2`
        .. warning:: arg2 must be non-zero.
        .. todo:: check that arg2 is non zero.
        """
        return arg1/arg2 + arg3

if __name__ == "__main__":
    import doctest
    doctest.testmod()