Sphinx和Docstrings中的reStructuredText：单反引号与双反引号或反引号的区别

Question

根据文档的说明，双反引号是用来表示字面量的，而单反引号则是用来表示需要被解释的代码文本。

这让我想到下面这个方法 f() 的文档字符串应该这样写：

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

提醒一下，别把Markdown中的反引号字符串和行内代码搞混了。

在Markdown中，根据CommonMark规范，以下几种写法是一样的：

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

• ...

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

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

---

而在reStructuredText中，单个反引号和双反引号的用法是不同的，具体区别如下：

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

  解释文本的渲染和含义依赖于特定的领域或应用。它可以用于索引条目或明确的描述性标记（比如程序标识符）。

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

  通常以等宽字体渲染。空格会被保留，但换行不会。

所以一般来说，reStructuredText中的双反引号包围的``code``和Markdown中单反引号包围的`code`是有点类似的。

Answer 2

来自Sphinx文档的内容：

默认角色（`content`）本身没有特别的含义。你可以随意使用它，比如用来表示变量名；如果你想把它设置成一个已知的角色，可以使用default_role这个配置项。

就个人习惯而言，在写Python的文档字符串时，我会用单个反引号来表示Python的名称和带点的路径，不管它们在文档字符串的位置是否可用。所以在你的例子中，我会把arg1、arg2、NiceClass、B和B.something都放在单个反引号里，必要时还可以加上合适的:class:、:mod:等角色。