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！
