[英]Colons in restructuredText inline literal
How can I make an inline literal with a colon in restructuredText? 如何在restructuredText中使用冒号创建内联文字?
I'm trying to document a Python function that returns a dictionary, eg, something like: 我正在尝试记录返回字典的Python函数,例如:
def function(...):
"""
...
Returns:
A dictionary mapping ``{id: {role: value}}``
"""
But when I compile with Sphinx, it complains: 但是当我用Sphinx编译时,它会抱怨:
WARNING: Inline literal start-string without end-string.
The literal end-string is certainly there, and it doesn't seem to violate other formatting rules , but I cannot get it to render the literal correctly with the colons (the braces aren't an issue; one: two
is also problematic inside an inline literal). 文字的结束字符串肯定存在,它似乎没有违反其他格式规则 ,但我不能让它用冒号正确渲染文字(括号不是问题;
one: two
也有问题内部内联文字)。 Escaping doesn't help: 逃避无济于事:
""" ``one\: two`` """ --> WARNING
""" ``one\\: two`` """ --> WARNING
r""" ``one\: two`` """ --> WARNING
The only thing that seems to work is a :code:
role: 似乎唯一有用的是
:code:
角色:
""" :code:`{one: {two: three}}` """ --> OK
Is this a limitation of Sphinx? 这是狮身人面像的限制吗? Or a bug with docutils?
或者是docutils的错误? Or is there a way to get colons inside inline literals?
或者有没有办法让冒号进入内联文字?
This behavior is not due to an inherent limitation of Sphinx, restructuredText, or autodoc, but in fact a bug in the (current version of the) Napoleon extension for processing Google-style docstrings. 此行为不是由于Sphinx,restructuredText或autodoc的固有限制,而实际上是用于处理Google风格文档字符串的(当前版本)Napoleon扩展中的错误。 Napoleon uses a regular expression to partition content on a colon, and it greedily consumes characters until it reaches the colon.
拿破仑使用正则表达式对冒号上的内容进行分区,它贪婪地消耗字符直到它到达冒号。 The reason it works with the
:code:
role is that Napoleon detects those before partitioning, but it does not detect the inline formatting (note that the problem also occurs with other inline formatting patterns, such as *emphasis*
or **strong**
). 它与
:code:
role一起工作的原因是拿破仑在分区之前检测到它们,但它没有检测到内联格式(请注意,其他内联格式化模式也会出现问题,例如*emphasis*
或**strong**
)。 One way to get around the bug, until it is fixed, is to place a colon before the inline literal: 解决bug的一种方法是在内联文字之前放置一个冒号,直到它被修复为止:
def function(a, b):
"""Put *a* and *b* in a dictionary.
Returns:
dict: ``{a: b}``
"""
return {a: b}
声明:本站的技术帖子网页,遵循CC BY-SA 4.0协议,如果您需要转载,请注明本站网址或者原文地址。任何问题请咨询:yoyou2525@163.com.