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

Question

我一直在阅读这个Example Google Style Python Docstrings文档来了解 Python 文档是如何编写的。但我无法理解一件事。

在记录字符串时，有这种奇怪的表示法。

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

Args: 
    arg1(str): The description for arg1

但是，在其他一些地方，文档是这样写的:

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

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

Answer 1

我认为 Python: Journey from Novice to Expert 中给出了您问题的答案.显然，如果你写 :obj:str，你的 Sphinx文档将包含指向标准 Python 文档中的 str 对象的链接。

顺便说一下，这种表示法并不局限于字符串。在 Example Google Style Python Docstrings 中 ExampleError 类的文档字符串中它说:

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