重组文本内联文字中的冒号

Question

如何在 restructuredText 中创建带冒号的内联文字？

我正在尝试记录一个 Python 函数，returns 一个字典，例如：

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、restructuredText 或 autodoc 的固有限制，而是实际上用于处理 Google 样式文档字符串的 Napoleon 扩展（当前版本）中的错误。 Napoleon 使用正则表达式在冒号上划分内容，它贪婪地消耗字符直到到达冒号。它与 :code: 角色一起工作的原因是 Napoleon 在分区之前检测到那些，但它没有检测到内联格式（请注意，其他内联格式模式也会出现此问题，例如 *emphasis* 或 **strong**).解决这个错误的一种方法，直到它被修复，是在内联文字之前放置一个冒号：

def function(a, b):
    """Put *a* and *b* in a dictionary.

    Returns:
        dict: ``{a: b}``
    """
    return {a: b}

重组文本内联文字中的冒号

Colons in restructuredText inline literal

python

restructuredtext

docutils

python-sphinx

autodoc