1

How can I make an inline literal with a colon in restructuredText?

I'm trying to document a Python function that returns a dictionary, e.g., something like:

def function(...):
    """
    ...
    Returns:
        A dictionary mapping ``{id: {role: value}}``
    """

But when I compile with Sphinx, it complains:

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). 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:`{one: {two: three}}` """  --> OK

Is this a limitation of Sphinx? Or a bug with docutils? Or is there a way to get colons inside inline literals?

goodmami
  • 962
  • 15
  • 26
  • Your example works in Sphinx 1.7.5 for me. Check your version. – Steve Piercy Jun 13 '18 at 21:51
  • I have Sphinx 1.7.5 and docutils 0.14. If I run the same file twice in a row, the warnings are not printed the second time, but the output is still incorrect. Did you verify that the whole literal string is rendered, and not just up to the first colon? – goodmami Jun 14 '18 at 03:31
  • @StevePiercy I notice that I only get the error for docstrings pulled in by autodoc, and not if I put the inline literal directly in a .rst file. Maybe autodoc is interfering, then? – goodmami Jun 14 '18 at 03:38
  • I tried it in both an .rst file and in a docstring of a module using autodoc with success both times. Perhaps you are not editing the file you think? – Steve Piercy Jun 14 '18 at 04:00
  • I think I've found the problem. It seems to be related to the use of the napoleon extension. See https://github.com/sphinx-doc/sphinx/issues/4016 and https://github.com/sphinx-doc/sphinx/issues/4021. Still investigating. – goodmami Jun 14 '18 at 04:03

1 Answers1

3

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. 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**). One way to get around the bug, until it is fixed, is to place a colon before the inline literal:

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

    Returns:
        dict: ``{a: b}``
    """
    return {a: b}
goodmami
  • 962
  • 15
  • 26