文档工具的王者Sphinx
Sphinx
https://www.sphinx.org.cn/
Sphinx是一个工具，可以轻松创建由Georg Brandl编写并根据BSD许可证授权的智能和美观文档
它最初是为Python文档创建的，它具有出色的工具，可用于各种语言的软件项目文档。 当然，这个站点也是使用reStructuredText源创建的
入门
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 基础上新增了许多指令和文本解释角色. 本章节是这些特性的参考资料.
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()
