python - restructedText 内联文字中的冒号

Question

如何在 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 的错误？或者有没有办法在内联文字中获取冒号？

Answer 1

此行为并不是由于 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}