Links to documentation in Read the Docs demo notebooks should stay within the same doc version #1402
Assignees
Labels
Comments
huonw
added
enhancement
This was referenced Apr 29, 2020
huonw
added a commit
that referenced
this issue
May 4, 2020
This updates any links to our Github demos folder to instead point to Read the Docs. The links within documentation _could_ be ``:doc:`... <demos/index>` `` relative links (or similar), but these will not work outside of Sphinx/Read the Docs (e.g. in `help(ClusterNodeGenerator)`). As such, this instead uses the full URLs always. To get the benefits of relative links (e.g. consistent versioning, and working locally without jumping out to the internet), we can post-process them in future (#1402 #1404). See: #1420
huonw
added a commit
that referenced
this issue
Jun 16, 2020
This extends our Sphinx link rewriting to also rewrite links to the published RTD docs `https://stellargraph.readthedocs.io/en/stable/...` to be relative internal links. This rewriting allows us to use external links in documentation that might be viewed outside of RTD (doc strings, notebooks), but still have the benefits of internal links: - more consistent experience with less "version jumping" - checking for validity This PR also does some validation of these URLs: that they always point to `https://stellargraph.readthedocs.io/en/stable/...`, not other versions or languages like `https://stellargraph.readthedocs.io/en/latest/...`. Examples: - `ClusterNodeGenerator` has a link to the Cluster-GCN demo as a full URL: https://github.com/stellargraph/stellargraph/blob/61b17d9ff7ec589273b545b58d4529192eeecad5/stellargraph/mapper/mini_batch_node_generators.py#L49 Being a full URL means that that's it's clickable (and loads a nicely rendered form) when someone does `help(ClusterNodeGenerator)` (or `?ClusterNodeGenerator` in a Jupyter cell), whereas the internal/Sphinx form ``:doc:`/demos/node-classification/cluster-gcn-node-classification` `` would not be. The URL means that one can change versions unexpectedly, e.g. clicking on the link in the develop (`.../latest/...`) docs (https://stellargraph.readthedocs.io/en/latest/api.html#stellargraph.mapper.ClusterNodeGenerator) will switch to the stable docs, and similarly for looking at any other version (such as a specific version like `.../1.0.0/...` or a PR build). With this PR, the link is rewritten inside Sphinx to be an internal reference, and so the link stays within a single version: e.g. https://stellargraph--1404.org.readthedocs.build/en/1404/api.html#stellargraph.mapper.ClusterNodeGenerator goes to https://stellargraph--1404.org.readthedocs.build/en/1404/demos/node-classification/cluster-gcn-node-classification.html - The GCN node classification demo links to various API elements, like the Cora datasets: https://github.com/stellargraph/stellargraph/blob/61b17d9ff7ec589273b545b58d4529192eeecad5/demos/node-classification/gcn-node-classification.ipynb#L128 As with `ClusterNodeGenerator`, having full URLs are good for someone viewing the notebook outside of the Sphinx rendering on RTD (e.g. editing it), but is unfortunate when on RTD. Current stable: https://stellargraph.readthedocs.io/en/stable/demos/node-classification/gcn-node-classification.html#2.-Creating-the-GCN-layers ("We can use StellarGraph’s GCN class (docs), which packages up the creation of this stack of graph convolution ...") Note that these actually switch from `.../stable/...` to `.../latest/...`. This PR also rewrites these links to the corresponding Sphinx form, like ``:py:mod:`...` `` for modules (which have `module-` in their URL fragment) or ``:py:any:`...` `` for other elements (which aren't distinguished in the URL fragment): https://stellargraph--1404.org.readthedocs.build/en/1404/demos/node-classification/gcn-node-classification.html#2.-Creating-the-GCN-layers This actually also catches two invalid links, where we rewrote the documentation paths from `stellargraph.layer.gcn.GCN` to `stellargraph.layer.GCN` (in #1157). - The README has a link to the GCN node classification demo and the demo indexing: 'its extended narrated notebook' & 'many more algorithms ...' (https://github.com/stellargraph/stellargraph#training-and-evaluation). Both of these rewritten in the corresponding part of the README on RTD: https://stellargraph--1404.org.readthedocs.build/en/1404/README.html#training-and-evaluation See: #1402
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Description
Several of our notebooks have links to our documentation, such as
stellargraph/demos/node-classification/gcn/gcn-cora-node-classification-example.ipynb
Line 125 in 625a99b
When published on Read the Docs (https://stellargraph.readthedocs.io/en/latest/demos/node-classification/gcn/gcn-cora-node-classification-example.html#Loading-the-CORA-network, although the link is broken at the time of writing, fixed by #1394), this link should point to the same version of the Read the Docs. Specifically, when viewing the
developdocs (.../latest/...), the link should stay on thedevelopdocs, but currently it always goes to.../stable/....Once we've done several stable releases with notebooks, like this, it'll ensure that looking at 1.0.0 notebooks always links to 1.0.0 documentation, and similarly for 1.1.0, etc.
The text was updated successfully, but these errors were encountered: