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_role配置值将其设置为已知角色。

作为个人偏好，在编写Python文档字符串时，我使用解释文本（单个反引号）来表示Python名称和虚线路径，无论它们是否在docstring位置的范围内。 所以在你的情况下，我会将arg1 ， arg2 ， NiceClass ， B和B.something全部放在单个反引号中，可选择添加相应的:class: ， :mod: etc.角色。

Answer 2

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

根据CommonMark规范 ，在Markdown中，这些是等价的：

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

• ...

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

  反引号字符串是一个由一个或多个反引号字符（`）组成的字符串，它既不是反引号，也不是反引号。

---

在reStructuredText中，单个反键环绕和双反键环绕是不同的 ：

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

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

• ``inline literal`` - > inline literal

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

所以一般来说，reStructuredText的双重反引号``code``在某种程度上等同于Markdown的单个反引号环绕`code` 。