如何在 restructedText 中制作带冒号的内联文字?
我正在尝试记录一个返回字典的 Python 函数,例如:
def function(...):
"""
...
Returns:
A dictionary mapping ``{id: {role: value}}``
"""
但是当我用 Sphinx 编译时,它会提示:
WARNING: Inline literal start-string without end-string.
文字结束字符串肯定存在,而且它似乎并不违反 other formatting rules ,但我无法让它用冒号正确渲染文字(大括号不是问题;在内联文字中 one:two
也有问题)。转义没有帮助:
""" ``one\: two`` """ --> WARNING
""" ``one\\: two`` """ --> WARNING
r""" ``one\: two`` """ --> WARNING
唯一有效的似乎是 :code:
角色:
""" :code:`{one: {two: three}}` """ --> OK
这是 Sphinx 的限制吗?或者 docutils 的错误?或者有没有办法在内联文字中获取冒号?
最佳答案
此行为并不是由于 Sphinx、restructedText 或 autodoc 的固有限制造成的,而是实际上 Napoleon 扩展(当前版本)中用于处理 Google 样式文档字符串的错误。 Napoleon 使用正则表达式对冒号上的内容进行分区,并且它会贪婪地消耗字符,直到到达冒号。它与 :code:
角色一起使用的原因是 Napoleon 在分区之前检测这些内容,但它不检测内联格式(请注意,其他内联格式模式也会出现该问题,例如 *强调*
或**强**
)。在修复该错误之前,解决该错误的一种方法是在内联文字之前放置一个冒号:
def function(a, b):
"""Put *a* and *b* in a dictionary.
Returns:
dict: ``{a: b}``
"""
return {a: b}
关于python - restructedText 内联文字中的冒号,我们在Stack Overflow上找到一个类似的问题: https://stackoverflow.com/questions/50845914/