Sphinx和Docstrings中的RestructuredText:单引号与双引号或反向引号差异

Question

从文档中可以看出,双引号用于文字,而单引号则在有代码文本被解释时使用.

这将导致我为f()下面的方法编写docstring :

class A(B):

    def f(arg1, arg2):
        return B(arg1 + arg2 + self.index)

如:

Takes two arguments, ``arg1` and ``arg2``, which are assumed to be objects
of type (or duck-type) `NiceClass`, and returns a new object of class `B`
with `B.something` assigned some hash of ``arg1`` and ``arg2``.

这是正确的吗？

在许多代码示例中,Sphinx和其他方面,我看到相当于B并NiceClass用双引号括起来("``B``"和"``NiceClass``").

Answer 1

从Sphinx文档:

默认情况下,默认角色(`content`)没有特殊含义.您可以随意使用它,例如变量名称; 使用default_roleconfig值将其设置为已知角色.

作为个人偏好的问题,在编写Python文档字符串时,我使用解释文本(单个反引号)来表示Python名称和虚线路径,无论它们是否在docstring位置的范围内.所以你的情况我会放arg1,arg2,NiceClass,B和B.something所有反单引号,需要添加相应的:class:,:mod:等角色.

Answer 2

只是提醒一下，不要与内联代码跨度的 Markdown 反引号字符串混淆。

在 Markdown 中，根据CommonMark Spec，这些是等效的：

• 纯文本视图 --> 渲染结果
• `inline literal` --> inline literal
• ``inline literal`` --> inline literal
• ```inline literal``` --> inline literal

• ...

  这是因为它们都被视为反引号字符串：

  反引号字符串是由一个或多个反引号字符 (`) 组成的字符串，前面和后面都没有反引号。

而在 reStructuredText 中，单反引号环绕和双反引号环绕 是不同的：

• `interpreted text` --> 渲染结果取决于不同的定义。

  解释文本的呈现和含义取决于域或应用程序。它可用于索引条目或显式描述性标记（如程序标识符）之类的东西。

• ``inline literal`` --> inline literal

  通常呈现为等宽文本。应该保留空格，但不会保留换行符。

所以总的来说，reStructuredText 的双反引号环绕``code``有点相当于 Markdown 的单反引号环绕 `code`。