-
Notifications
You must be signed in to change notification settings - Fork 129
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
Comments
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 |
No, not out of the box. How would you imagine a feature like this should work? Currently, this would be the way to go:
|
nbsphinx doesn't support that yet, see spatialaudio/nbsphinx#301
nbsphinx doesn't support that yet, see spatialaudio/nbsphinx#301
nbsphinx doesn't support that yet, see spatialaudio/nbsphinx#301
nbsphinx doesn't support that yet, see spatialaudio/nbsphinx#301
nbsphinx doesn't support that yet, see spatialaudio/nbsphinx#301
A special scheme,
which maps to
|
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 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. |
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
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.
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.
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.
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:
Which generated a link that looks like
validate_component
. Switching over to Markdown, I have this:Which does not yield a code block with a link but rather this in plaintext:
I resolved the issue by removing the `s but this is suboptimal, since the code isn't clearly offset.
The text was updated successfully, but these errors were encountered: