Python文档(:obj:`str`)vs(str)

Question

我一直在阅读这个示例Google样式Python文档字符串文档,以了解如何编写好的Python文档.但我无法理解一件事.

记录字符串时,有一种奇怪的表示法.

例如,在记录参数时,文档指定它们的写法如下:

Args: 
    arg1(str): The description for arg1

但是,在其他一些地方,该文件写道:

Args: 
    param2 (:obj:`str`, optional): The second parameter.

在第二种情况下,为什么字符串表示为:obj:`str`而不仅仅是普通的str？为什么首先有两个表示strings？我什么时候使用哪个？

Answer 1

我认为你的问题的答案在《Python：从新手到专家的旅程》中给出 。显然，如果您编写:obj:str，您的Sphinxstr文档将包含标准 Python 文档中该对象的链接。

顺便说一句，这种表示法并不限于字符串。在Google Style Python DocstringsExampleError中的类的文档字符串中，它表示：

Args:
    msg (str): Human readable string describing the exception.
    code (:obj:`int`, optional): Error code.