Previously, I used links to stable for documentation links in the notebook. However, it is better to use latest since this notebook will appear in the following places:
GitHub, where it is on master branch and thus should reference the master branch documentation
Colab, when opened from the latest version
At the same time, we need a version of the notebook with stable links for when users open from the stable version. This requires a script which will replace the links before documentation deployment.
Options for the script include:
Integrate with Sphinx since that is what ReadTheDocs calls -- this involves making a callback like the following in conf.py
def replace_notebook_links(app, docname, source):
"""Replaces "latest" links with "stable" links in notebooks if building the
stable version.
See https://www.sphinx-doc.org/en/master/extdev/appapi.html#event-source-read
"""
def setup(app):
app.connect("source-read", replace_notebook_links)
This fails for Google Colab links opened from the stable version of the documentation -- it will reference a GitHub notebook which still has "latest" links.
Modify the deployment to include replacing the links on the GitHub version for the release only. This makes the deployment process more complicated as we also have to revert the changes after the release.
Deploy to somewhere else and open the notebook from there instead. One problem is that we're using GitHub as a CDN, but Colab would not allow opening from an arbitrary URL (i.e. it must be a GitHub link). Thus, we will modify the deployment.
Description
Previously, I used links to
stablefor documentation links in the notebook. However, it is better to uselatestsince this notebook will appear in the following places:At the same time, we need a version of the notebook with stable links for when users open from the stable version. This requires a script which will replace the links before documentation deployment.
Options for the script include:
Integrate with Sphinx since that is what ReadTheDocs calls -- this involves making a callback like the following in
conf.pyThis fails for Google Colab links opened from the stable version of the documentation -- it will reference a GitHub notebook which still has "latest" links.
TODO
Questions
Status
yapfpytestpylintHISTORY.md