Sphinx和Docstrings中的reStructuredText：单引号与双引号或反向引号差异

Question

From the documentation, it appears that the double back-quote is used for literals, while the single back-quote is used when there is code text to be intepreted.

This would lead me to to write the docstring for method f() below:

class A(B):

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

As:

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

Would this be correct?

In many code examples, Sphinx and otherwise, I see the equivalent of B and NiceClass wrapped in double back-quotes ("``B``" and "``NiceClass``").

Answer 1

From the Sphinx documentation :

The default role (`content`) has no special meaning by default. You are free to use it for anything you like, eg variable names; use the default_role config value to set it to a known role.

As a matter of personal preference, when writing Python docstrings, I use interpreted text (single backquotes) for Python names and dotted paths, whether or not they are in scope at the location of the docstring. So in your case I would put arg1 , arg2 , NiceClass , B and B.something all in single backquotes, optionally adding the appropriate :class: , :mod: etc. roles.

Answer 2

Just a reminder, not to be confused with Markdown's backtick string for inline code span.

In Markdown, according to the CommonMark Spec , these are equivalent:

• Plain text view --> Render results
• `inline literal` --> inline literal
• ``inline literal`` --> inline literal
• ```inline literal``` --> inline literal

• ...

  This is because they are all seen as the backtick string :

  A backtick string is a string of one or more backtick characters (`) that is neither preceded nor followed by a backtick.

---

While in reStructuredText, single backtick surround and double backticks surround are different :

• `interpreted text` --> the render result is depended on different definitions.

  The rendering and meaning of interpreted text is domain- or application-dependent. It can be used for things like index entries or explicit descriptive markup (like program identifiers).

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

  Normally rendered as monospaced text. Spaces should be preserved, but line breaks will not be.

So in general, reStructuredText's double backticks surround ``code`` is somewhat equivalent to Markdown's single backtick surround `code` .