Sphinx add code formatting to :ref:

Question

I would like to add code formatting to a reference like this:

:ref:`__slots__ <python:slots>`

My intersphinx_mapping defines python like this:

intersphinx_mapping = {
    'python': ('https://docs.python.org/3', None),
}

so the link is to https://docs.python.org/3/reference/datamodel.html#slots (slots is defined in the std:label section of https://docs.python.org/3/objects.inv)

My goal is to format the rendered link in the style of :py:attr: or similar rather than the default text style with which :ref: renders.

None of the following options work:

... ``:ref:`__slots__ <python:slots>``` ... yeilds output like

... :ref:`__slots__ <python:slots>` ...
... ``:ref:`__slots__ <python:slots>` `` ... yeilds output like

... __slots__ ...
... :ref:```__slots__`` <python:slots>` ... yeilds output like

... :ref:```__slots__`` <python:slots>` ...

There are two separate internal links to #id1 in this case.
... :ref:` ``__slots__`` <python:slots>` ... yeilds output like

... :ref:` ``__slots__`` <python:slots>` ...

Relpacing ``...`` with :code:`...` or :literal:`...` either inside or outside the :ref: does not help any either. In fact, it appears that nested roles are not allowed at all.

I would like to have an inline role that results in something that renders with a code style and a link, like

... __slots__ ...

How do I get the basic :ref: (or equivalent) to appear with the code-style formatting used by :py:attr:?

I am using Sphinx 1.6.3 with Python 3.6.2 in an Anaconda environment.

Inverse question is here: Sphinx remove code formatting from custom code reference

A tangentially relevant question: Nested / Compounded roles: apply multiple roles to overlapping text

I'm a little confused by what you want. First, do you want this inline and not in a code-block? Second, do you want the rendered output to be linked to the Python docs for slots? Finally, do you want to apply a style to the rendered output? — Steve Piercy
@StevePiercy. Apologies for the confusion. 1) I would like the :ref: (or equivalent) to be inline, as it currently is. 2) I would like the output to be linked to the python docs with label slots. 3) I would like the output to be rendered in code font, even though :ref: is not. Preferably with the style of :py:attr: for this case. If that means applying a style to it, I would be happy to do so. — Mad Physicist
I don't think this is possible. See my answer to your inverse question. — Steve Piercy
Could I somehow define a custom role based on ref that just adds the same formatting as :py:attr:? — Mad Physicist

mzjn mzjn · Accepted Answer · 2017-08-18T14:26:12

The :any: role does what you want:

:any:`__slots__ <python:slots>`

This is a "convenience role" that looks for cross-reference targets in the current domain as well as targets that work with :ref:.

The Python domain has several specific cross-reference roles, for different types of objects.

Sphinx add code formatting to :ref:

1 Answers