Python/ target=_blank class=infotextkey>Python 正在成为当今流行的编程语言。 对于任何编码项目,文档是提高代码可读性的最重要部分,但同时也是最被忽略的部分! 为了解决这个问题,Sphinx 工具派上用场了,它可以自动化文档部分
现在您已经了解 Sphinx 并知道如何使用它。 让我们知道最常用的文档字符串格式,即 google、NumPy 和 Sphinx 文档字符串格式。
1.Google Docstring
这种文档字符串格式是可汗学院推荐的,俗称“Google Docstring”。 为了确保文档字符串与 Sphinx 兼容并被 Sphinx 的自动文档识别,请在 conf.py 文件中添加 sphinx.ext.napoleon 扩展名。 文档字符串格式为:
def google_docstrings(num1, num2
) -> int:
"""Add up two integer numbers.
This function simply wraps the ``+`` operator, and does not
do anything interesting, except for illustrating what
the docstring of a very simple function looks like.
Args:
num1 (int) : First number to add.
num2 (int) : Second number to add.
Returns:
The sum of ``num1`` and ``num2``.
RAIses:
AnyError: If anything bad hAppens.
"""
return num1 + num2
2. NumPy 文档字符串
这种文档格式用于 NumPy、SciPy 和 Pandas 等主要数据科学库。 就像 Google 的文档字符串一样,要使其与 Sphinx 兼容,您必须在 conf.py 文件中添加 sphinx.ext.napoleon 扩展名。 文档字符串的格式为:
def numpy_docstrings(num1, num2) -> int:
"""
Add up two integer numbers.
This function simply wraps the ``+`` operator, and does not
do anything interesting, except for illustrating what
the docstring of a very simple function looks like.
Parameters
----------
num1 : int
First number to add.
num2 : int
Second number to add.
Returns
-------
int
The sum of ``num1`` and ``num2``.
Raises
======
MyException
if anything bad happens
See Also
--------
subtract : Subtract one integer from another.
Examples
--------
>>> add(2, 2)
4
>>> add(25, 0)
25
>>> add(10, -10)
0
"""
return num1 + num2
3.Sphinx 文档字符串
没有什么比旧的 sphinx 文档字符串更好的了,这是使用的最基本的文档字符串格式,但在视觉上有些密集,因此难以阅读。 相同的格式是:
def sphinx_docstrings(num1, num2) -> int:
"""Add up two integer numbers.
This function simply wraps the ``+`` operator, and does not
do anything interesting, except for illustrating what
the docstring of a very simple function looks like.
:param int num1: First number to add.
:param int num2: Second number to add.
:returns: The sum of ``num1`` and ``num2``.
:rtype: int
:raises AnyError: If anything bad happens.
"""
return num1 + num2
结论
除了上述格式之外,还有许多可用于 Python 的 docstring 格式,我们在这场比赛中没有一个赢家。
所以选择你喜欢的格式,不要混合格式,并在整个项目中坚持下去。 我个人最喜欢的是 NumPy 的 Docstring!