nbsphinx
nbsphinx copied to clipboard
Link with code does not format properly
I am trying to switch my docs over to nbsphinx and am running into a bit of a strange issue. I used to refer to a function like this:
:func:`~mechwolf.validate_component`
Which generated a link that looks like validate_component. Switching over to Markdown, I have this:
[`validate_component`](../api/mechwolf.rst#mechwolf.validate_component)
Which does not yield a code block with a link but rather this in plaintext:
`validate_component <../api/mechwolf.rst#mechwolf.validate_component>`__
I resolved the issue by removing the `s but this is suboptimal, since the code isn't clearly offset.
This is a known limitation of the reStructuredText format, see http://docutils.sourceforge.net/FAQ.html#is-nested-inline-markup-possible.
AFAICT, the only way to fix this is #36.
If you know a different way to solve this, please let me know!
I understand. Is there a way to make a link into a :func: role?
No, not out of the box. How would you imagine a feature like this should work?
Currently, this would be the way to go:
[validate_component](../api/mechwolf.rst#mechwolf.validate_component)
How would you imagine a feature like this should work?
A special scheme,
[some text](sphinx-role://some role/some object)
which maps to
:some role:`some text <some object>`
Something like this could work, but the problem is that it would lead to an invalid link when using the notebook in Jupyter.
A link like [validate_component](../api/mechwolf.rst#mechwolf.validate_component) would at least be a valid link to the .rst source file (even though the part after # wouldn't really work).
If you are willing to write invalid links in your notebook, you might as well just use a raw reST cell to create your link.
Another problem might be the spaces in the URL. Some Markdown dialects don't allow that.