从文档中可以看出双引号用于 文字,而当有代码文本被解释时使用单个反引号。
这将导致我为下面的方法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``” )。
答案 0 :(得分:10)
默认情况下,默认角色(`content`)没有特殊含义。您可以随意使用它,例如:变量名;使用
default_role
配置值将其设置为已知角色。
作为个人喜好,在编写Python文档字符串时,我使用解释性文本(单个反引号)来表示Python名称和虚线路径,无论它们是否在docstring位置的范围内。因此,在您的情况下,我会将arg1
,arg2
,NiceClass
,B
和B.something
全部放在单个反引号中,可选择添加相应的:class:
,:mod:
等角色。
答案 1 :(得分:2)
提醒一下,不要与Markdown的内向代码范围的反引号字符串相混淆。
在Markdown中,根据CommonMark Spec,这些是等效的:
`inline literal`
-> inline literal
``inline literal``
-> inline literal
```inline literal```
-> inline literal
...
这是因为它们都被视为backtick string:
反引号字符串是由一个或多个反引号字符(`)组成的字符串,该字符既不能在反引号之前也不能在反引号之后。
在reStructuredText中,单反引号环绕和双反引号环绕 are different:
`interpreted text`
->渲染结果取决于不同的定义。
解释文本的呈现和含义是域或 取决于应用程序。它可以用于索引条目之类的东西 或明确的描述性标记(如程序标识符)。
``inline literal``
-> inline literal
通常呈现为等宽文本。应该保留空格,但不能保留换行符。
因此,通常来说,reStructuredText的双反引号包围``code``
有点等同于Markdown的单反引号包围`code`
。