nbsphinx can't handle links formatted as code

[kevinsung]

Example:

The How to build and transpile Qiskit quantum circuits notebook begins with the markdown

In this guide, we show how to use the [ffsim.qiskit](../api/ffsim.qiskit.rst) module to build and transpile fermionic quantum circuits.

which is rendered correctly as

However, ideally ffsim.qiskit would be written in code style, ffsim.qiskit. If I try surrounding it in backticks,

In this guide, we show how to use the [`ffsim.qiskit`](../api/ffsim.qiskit.rst) module to build and transpile fermionic quantum circuits.

then it gets rendered incorrectly as

The link looks fine in Jupyter, it's just the rendered Sphinx docs that is bad.

[bartandrews]

I don't have an immediate solution to this but I can provide some information that might be useful.

The problem is the nested inline formatting, i.e. that you would like both literal and link formatting at the same time. For RST files, this can be achieved with a combination of the sphinx.ext.extlinks and sphinxnotes.comboroles extensions.

The extlinks extension allows you to shorten URLs into roles. For example, in conf.py you could define

extlinks = {
    'api': ('../api/%s.rst', '%s'),
}

And then, in an RST file, you could write :api:ffsim.qiskit to generate a hyperlink to that file.

The comboroles extension allows you to combine roles, for example in conf.py you can add

comboroles_roles = {
    'literal_api': ['literal', 'api'],
}

Then, in an RST file, you can write :literal_api:ffsim.qiskit to get the desired result.

However, the additional problem is that within an ipynb file, the text is rendered as markdown. Hence, the [name](link) syntax. MyST is a combination of md and rst that could help here. You already have the myst_parser that renders all md files as myst. However, if you'd like to render all md files and ipynb files as myst, then you would need the myst_nb extension instead (this would replace myst_parser) https://myst-nb.readthedocs.io/en/latest/index.html

This should then allow you to use RST role directives in the ipynb text, and then you can use the extlinks+comboroles trick to render it as a literal link. I'm not sure if it's worth going into all that effort though :sweat_smile: Maybe there is an easier way...

[SilverRainZ]

Easier way: extlink + css style, see https://github.com/sphinx-doc/sphinx/pull/12319