Formatting “之间的区别：&引用&引用@&引用；python文档字符串中没有任何内容

我只是想更好地了解Python docstring的布局（在

之间）

我见过不同布局的文档字符串…例如

"""
@DESCRIPTION
Ive seen tags STARTING with an at-sign

:DESCRIPTION:
Tags with colons

DESCRIPTION
And tags with nothing

"""

这些都有功能作用吗？
@
与长生不老药有关吗？或者这些只是开发者的偏好？我已经浏览了docstring的样式指南，但看不到它在哪里解决了这些问题

谢谢
 如果要将docstring转换为文档，可以添加额外的标记，以帮助正在使用的文档工具应用其他格式

@
用于指示字段

分号
：
是斯芬克斯的rst（请参阅文档或上面的链接）

这里有一个相关帖子：

可能还有其他用途（可能包括长生不老药，我对这项技术还不太熟悉，无法评论）

希望有帮助。

Python DocString可以按以下几种格式编写：

-Javadoc
从历史上看，类似javadoc的风格很流行。它被（使用称为
Epytext
格式）用于生成文档

例如：

"""
This is a javadoc style.

@param param1: this is a first param
@param param2: this is a second param
@return: this is a description of what is returned
@raise keyError: raises an exception
"""

"""
This is a reST style.

:param param1: this is a first param
:param param2: this is a second param
:returns: this is a description of what is returned
:raises keyError: raises an exception
"""

"""
This is a groups style docs.

Parameters:
    param1 - this is the first param
    param2 - this is a second param

Returns:
    This is a description of what is returned

Raises:
    KeyError - raises an exception
"""

-休息
现在，可能更流行的格式是用于生成文档的重构文本（reST）格式

例如：

"""
This is a javadoc style.

@param param1: this is a first param
@param param2: this is a second param
@return: this is a description of what is returned
@raise keyError: raises an exception
"""

"""
This is a reST style.

:param param1: this is a first param
:param param2: this is a second param
:returns: this is a description of what is returned
:raises keyError: raises an exception
"""

"""
This is a groups style docs.

Parameters:
    param1 - this is the first param
    param2 - this is a second param

Returns:
    This is a description of what is returned

Raises:
    KeyError - raises an exception
"""

-谷歌
谷歌有自己的格式，这是很常用的。它也可以用斯芬克斯来解释。请注意，Numpy建议遵循他们自己的numpydoc，它基于Google格式，可供Sphinx使用

例如：

"""
This is a javadoc style.

@param param1: this is a first param
@param param2: this is a second param
@return: this is a description of what is returned
@raise keyError: raises an exception
"""

"""
This is a reST style.

:param param1: this is a first param
:param param2: this is a second param
:returns: this is a description of what is returned
:raises keyError: raises an exception
"""

"""
This is a groups style docs.

Parameters:
    param1 - this is the first param
    param2 - this is a second param

Returns:
    This is a description of what is returned

Raises:
    KeyError - raises an exception
"""

转换/生成
可以使用一种工具，如自动生成docstring到尚未记录的Python项目，或者将现有docstring（可以混合多种格式）从一种格式转换为另一种格式

注：示例取自。有关docstring的更多信息，请参见。
回答得很好。但我刚刚花了一个多小时试图将reST格式的pydocs转换成HTML或Markdown之类的东西，我对其中明显涉及的设置量感到惊讶，例如Sphinx。我想象一些实用程序可以直接做到这一点。你知道这样一个工具吗，或者你能指出一些明确的步骤吗？谢谢@MichaelScheper你可以看看