nbsphinx icon indicating copy to clipboard operation
nbsphinx copied to clipboard

Link with code does not format properly

Open Benjamin-Lee opened this issue 6 years ago • 5 comments

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.

Benjamin-Lee avatar Apr 26 '19 07:04 Benjamin-Lee

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!

mgeier avatar Apr 26 '19 11:04 mgeier

I understand. Is there a way to make a link into a :func: role?

Benjamin-Lee avatar Apr 26 '19 22:04 Benjamin-Lee

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)

mgeier avatar Apr 28 '19 17:04 mgeier

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>`

eric-wieser avatar Feb 24 '20 17:02 eric-wieser

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.

mgeier avatar Feb 25 '20 09:02 mgeier