restructuredText 内联文字中的冒号答案

【问题标题】：Colons in restructuredText inline literalrestructuredText 内联文字中的冒号
【发布时间】：2018-11-23 13:09:29
【问题描述】：

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

我正在尝试记录一个返回字典的 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 1.7.5。检查您的版本。
我有 Sphinx 1.7.5 和 docutils 0.14。如果我连续两次运行同一个文件，第二次不会打印警告，但输出仍然不正确。您是否验证了整个文字字符串已呈现，而不仅仅是第一个冒号？
@StevePiercy 我注意到我只收到自动文档提取的文档字符串的错误，而不是如果我将内联文字直接放在 .rst 文件中。那么，也许 autodoc 有干扰？
我在 .rst 文件和使用 autodoc 的模块的文档字符串中都尝试过，两次都成功。也许您没有编辑您认为的文件？
我想我找到了问题所在。这似乎与拿破仑扩展的使用有关。请参阅 github.com/sphinx-doc/sphinx/issues/4016 和 github.com/sphinx-doc/sphinx/issues/4021。仍在调查中。

标签： python python-sphinx restructuredtext autodoc docutils

【解决方案1】：

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

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

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

【讨论】：