Sphinx和Docstrings中的RestructuredText:单引号与双引号或反向引号差异

时间:2014-03-07 17:40:54

标签: python python-sphinx restructuredtext docstring

从文档中可以看出双引号用于 文字,而当有代码文本被解释时使用单个反引号。

这将导致我为下面的方法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和其他方面,我看到等同于BNiceClass包含在双引号中(“``B``”和“``NiceClass``” )。

2 个答案:

答案 0 :(得分:10)

来自Sphinx documentation

  

默认情况下,默认角色(`content`)没有特殊含义。您可以随意使用它,例如:变量名;使用default_role配置值将其设置为已知角色。

作为个人喜好,在编写Python文档字符串时,我使用解释性文本(单个反引号)来表示Python名称和虚线路径,无论它们是否在docstring位置的范围内。因此,在您的情况下,我会将arg1arg2NiceClassBB.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`