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

Link with code does not format properly #301

Open
Benjamin-Lee opened this issue Apr 26, 2019 · 5 comments
Open

Link with code does not format properly #301

Benjamin-Lee opened this issue Apr 26, 2019 · 5 comments

Comments

@Benjamin-Lee
Copy link

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.

@mgeier
Copy link
Member

mgeier commented Apr 26, 2019

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!

@Benjamin-Lee
Copy link
Author

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

@mgeier
Copy link
Member

mgeier commented Apr 28, 2019

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 added a commit to mgeier/ipywidgets that referenced this issue Jan 5, 2020
nbsphinx doesn't support that yet, see
spatialaudio/nbsphinx#301
mwcraig pushed a commit to mgeier/ipywidgets that referenced this issue Jan 7, 2020
nbsphinx doesn't support that yet, see
spatialaudio/nbsphinx#301
pbugnion pushed a commit to pbugnion/ipywidgets that referenced this issue Jan 8, 2020
nbsphinx doesn't support that yet, see
spatialaudio/nbsphinx#301
mwcraig pushed a commit to mgeier/ipywidgets that referenced this issue Jan 8, 2020
nbsphinx doesn't support that yet, see
spatialaudio/nbsphinx#301
mwcraig pushed a commit to mgeier/ipywidgets that referenced this issue Jan 8, 2020
nbsphinx doesn't support that yet, see
spatialaudio/nbsphinx#301
@eric-wieser
Copy link

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

@mgeier
Copy link
Member

mgeier commented Feb 25, 2020

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.

huonw added a commit to stellargraph/stellargraph that referenced this issue May 1, 2020
This means that all instances of nested formatting in our notebooks don't work
(spatialaudio/nbsphinx#301), including examples like
the above and also, more often, formatting within or around links:

```markdown
[some `code` in a link](url)
***[bold italic link](url)***
```

This PR removes all instances of this, in two ways:

| description                        | before                        | after                        |
|------------------------------------|-------------------------------|------------------------------|
| removing formatting                | ***text*** ***[link](#url)*** | **text**<br>[link](#url)     |
| moving link (especially doc links) | [some `method`](#url)         | some `method` ([docs](#url)) |

This removal was driven by extending the `notebook_text_checker` script to find
instances of this, using a real Markdown parser (#1393). The script will ensure
that we don't have more instances come into our notebooks in future.

Example of failure on CI (with the notebooks that were updated here):
https://buildkite.com/stellar/stellargraph-public/builds/3610#annotation-notebook_text_checker

I checked some of the instances I fixed here in the existing documentation, and
all of them were rendered incorrectly, validating that this is useful.

Examples:

- links in GCN node classification:
  Before:
  https://stellargraph.readthedocs.io/en/v1.0.0rc1/demos/node-classification/gcn/gcn-cora-node-classification-example.html#Loading-the-CORA-network
  After:
  https://stellargraph--1394.org.readthedocs.build/en/1394/demos/node-classification/gcn/gcn-cora-node-classification-example.html#Loading-the-CORA-network
- paper reference in Attri2Vec node classification
  Before:
  https://stellargraph.readthedocs.io/en/v1.0.0rc1/demos/node-classification/attri2vec/attri2vec-citeseer-node-classification-example.html
  After:
  https://stellargraph--1394.org.readthedocs.build/en/1394/demos/node-classification/attri2vec/attri2vec-citeseer-node-classification-example.html

All new docs:
https://stellargraph--1394.org.readthedocs.build/en/1394/demos/index.html

See: #1292
andsteing added a commit to andsteing/flax that referenced this issue Oct 16, 2021
Unfortunately, "source formatted" links like

see [`optax`](https://optax.readthedocs.io/)

are not supported in RST:

- spatialaudio/nbsphinx#301
- https://docutils.sourceforge.io/FAQ.html#is-nested-inline-markup-possible

So removing the "source formatting" so these links render as normal text (but
with correct link formatting) in both Colab and RTD.
NeilGirdhar pushed a commit to NeilGirdhar/flax that referenced this issue Jan 25, 2022
Unfortunately, "source formatted" links like

see [`optax`](https://optax.readthedocs.io/)

are not supported in RST:

- spatialaudio/nbsphinx#301
- https://docutils.sourceforge.io/FAQ.html#is-nested-inline-markup-possible

So removing the "source formatting" so these links render as normal text (but
with correct link formatting) in both Colab and RTD.
andsteing added a commit to andsteing/flax that referenced this issue Jan 26, 2022
Unfortunately, "source formatted" links like

see [`optax`](https://optax.readthedocs.io/)

are not supported in RST:

- spatialaudio/nbsphinx#301
- https://docutils.sourceforge.io/FAQ.html#is-nested-inline-markup-possible

So removing the "source formatting" so these links render as normal text (but
with correct link formatting) in both Colab and RTD.
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