Rewrite README links in notebooks to point to Sphinx index files #1401
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
|
Check out this pull request on You'll be able to see Jupyter notebook diff and discuss changes. Powered by ReviewNB. |
|
Code Climate has analyzed commit e319234 and detected 1 issue on this pull request. Here's the issue category breakdown:
View more on Code Climate. |
huonw
added a commit
that referenced
this pull request
Apr 30, 2020
…1398) The raw HTML table was not converting to reStructuredText through `nbsphinx` (which, I think, uses `jupyter nbconvert --to=rst`, which uses pandoc). The output lost the links + images (see more details about `pandoc` in #1398). This PR updates the links to be normal markdown links + images, which ensures they do get converted correctly. To distinguish these links from normal body text, these are formatted as a block-quote (`> ...`). This gives acceptable (not great) formatting on each of the major platforms one might be using to look at this (see images in #1398): - Jupyter locally - Github: https://github.com/stellargraph/stellargraph/blob/2972637ec3b75c7ab7bc6a7a96697489b03f62fd/demos/basics/loading-networkx.ipynb - nbviewer: https://nbviewer.jupyter.org/github/stellargraph/stellargraph/blob/2972637ec3b75c7ab7bc6a7a96697489b03f62fd/demos/basics/loading-networkx.ipynb - Read the Docs: https://stellargraph--1398.org.readthedocs.build/en/1398/demos/basics/loading-networkx.html Note that both Github and nbviewer have CSS that forces images to be formatted as block elements, and so they're positioned separately (instead of inline elements as is the default). This is unfortunate, but per #1391, we're moving towards Read the Docs being the main online display of our demos. We can potentially improve the Read the Docs formatting with custom CSS or some post-processing (similar to #1401). See: #1293
timpitman
approved these changes
Apr 30, 2020
There was a problem hiding this comment.
Looks from https://readthedocs.org/api/v2/build/10932108.txt that this removed a bunch of warnings of bad links 👍
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Our demo notebooks contain links to READMEs. These links don't work on Read the Docs/in Sphinx, because we have
index(per the web server convention) files for each directory, not READMEs.This PR writes a basic sphinx extension that rewrites any relative links to a file called "README.md" to instead be a link to "index.txt", matching our Sphinx index files. I modelled this after:
This approach allows us to retain links to READMEs in the notebooks, so that they work locally and on Github. These links are probably useful even with the move to Read the Docs being the canonical display of demos (#1391), due to being useful locally. (A simpler approach that breaks this would be to change the links to be correct for Read the Docs within each notebook.)
This also adjusts the case of one of the
connector/neo4jREADME file, so that it's consistent with the rest of the repo, to make this code simpler.This fixes 12 out of 66 of the remaining warnings in #1360; all of the ones like:
Example: in the GCN node classification notebook (https://github.com/stellargraph/stellargraph/blob/1cca6b6c6f4cd1fea7c6932918cba18d15eef6d4/demos/node-classification/gcn/gcn-cora-node-classification-example.ipynb), there's a conclusion that includes links to both the parent node-classification README and the all notebooks README. Its Markdown source is:
Before: https://stellargraph.readthedocs.io/en/latest/demos/node-classification/gcn/gcn-cora-node-classification-example.html#Conclusion These links stayed pointing to
README.mdin the respective parent directories, which don't exist in the Sphinx docs/on Read the Docs, and so they're dead links. Generated HTML (note theexternalCSS class, and thehref=.../README.md):After: https://stellargraph--1401.org.readthedocs.build/en/1401/demos/node-classification/gcn/gcn-cora-node-classification-example.html#Conclusion The links were rewritten and now work. Generated HTML (note the
internalCSS class, and thehref=.../index.html):See: #1292