Embedded external URL breaks Sphinx?

Question

I am trying to document some Python code with Sphinx, and I've added the following doc comment to a constant.

#: `RFC 8415 §7.6 <https://www.rfc-editor.org/rfc/rfc8415.html#section-7.6>`_
_SOL_TIMEOUT = 1

This appears to break Sphinx; it considers anything before the colon to be a type identifier, so the result is something like:

pkg.module._SOL_TIMEOUT=1

/www.rfc-editor.org/rfc/rfc8415.html#section-7.6>`_

Type:: `RFC 8415 §7.6 <https

(That's as close as I can get with Markdown.)

Is there any way to make embedded external URLs work with Sphinx, or am I stuck with the named URL syntax?

(Just for the record, I have tried replacing the non-ASCII '§' with an simple 'S'; the change had no effect on the behavior that I'm seeing.)

mzjn · Answer 1 · 2023-02-25T11:25:12.563

It does not seem to be possible to do this with a one-line doc comment (#: ...). However, a working link is produced with two doc comments:

#: First doc comment (cannot be empty).
#: `RFC 8415 §7.6 <https://www.rfc-editor.org/rfc/rfc8415.html#section-7.6>`_
_SOL_TIMEOUT = 1

It can also be made to work with a docstring.

An embedded URL is OK if the link is not in the first line (paragraph):

_SOL_TIMEOUT = 1
"""First line of docstring.

`RFC 8415 §7.6 <https://www.rfc-editor.org/rfc/rfc8415.html#section-7.6>`_
"""

The other option is a named URL (separating the link and the target definition):

_SOL_TIMEOUT = 1
"""`RFC 8415 §7.6`_

.. _RFC 8415 §7.6: https://www.rfc-editor.org/rfc/rfc8415.html#section-7.6
"""

1 Answers1