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` 。