reStructuredText in Sphinx and Docstrings: single vs. double back-quotes or back-ticks difference

From the Sphinx documentation:

The default role (`content`) has no special meaning by default. You are free to use it for anything you like, e.g. 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.


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