The easiest way is orobably to add a CSS class but that would require doing it for all themes. I think the options approach is better. Unfortunately I don't have time for that :(

I want to do this, with a menu of choices to include bold/italic/literal.

This probably requires changing extlinks to be a dict rather than tuple, though, for readability. The tuple format would be retained but not allow for any formatting or other advanced features.

A

I wrote an extension for composing simple roles (more precisely, it composes the TextElements produced after roles run, if @hugovk doesn't mind using a third-party extension, this issue can be implemented without changing extlink:

for example, we can compose literal and cpy-file in conf.py:

extensions.append('sphinxnotes.comboroles')
comboroles_roles = {
    'cpy-file2': ['literal', 'cpy-file'],
}

by using :cpy-file2:`conf.py role we can be pseudo-nodes like:

<literal>
    <reference uri="https://github.com/python/cpython/blob/main/conf.py">
      conf.py

See https://sphinx.silverrainz.me/comboroles/examples.html#sphinx-ext-extlink for more details.

@SilverRainZ Thanks for mentioning the extension! If this is coming to Sphinx, then it can wait. My initial plan was to use this for the CPython devguide and PEPs repos, which can use extensions. If we wanted to also use it for CPython itself, then it's better to avoid extensions because we need to make sure the docs build without any for downstream redistributors.

Describe alternatives you've considered

Use CSS?

I'm now thinking this is the best option: it gives theme authors and docs builders the most flexibility to format the extlink in whatever way they want, without being tied to whatever formatting has been implemented in Sphinx.

It's also a very small change to Sphinx (two lines of code + two lines of tests) and requires no backwards compatibility concerns around maintaining both tuples and dicts for config.

More specifically for CPython, if a Linux distributor builds the docs with an older version of Sphinx, it will still build the docs, they just won't get the CSS class and will get the plain formatting, which I'm not worried about.

Please see PR #12319.