reStructuredText in Sphinx and Docstrings: single vs. double back-quotes or back-ticks difference
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“”).
Answers:
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`
.
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“”).
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`
.