Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

nbsphinx can't handle links formatted as code #164

Open
kevinsung opened this issue May 5, 2024 · 2 comments
Open

nbsphinx can't handle links formatted as code #164

kevinsung opened this issue May 5, 2024 · 2 comments

Comments

@kevinsung
Copy link
Collaborator

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

image

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

image

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

@bartandrews
Copy link
Contributor

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 😅 Maybe there is an easier way...

@SilverRainZ
Copy link

Easier way: extlink + css style, see sphinx-doc/sphinx#12319

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

3 participants