Package: rtds-action
Interface Read the Docs and GitHub ActionsI like to useRead the Docsto build (and version!) my
docs, but Ialsolike to useJupyter notebooksto
write tutorials. Unfortunately, even thoughnotebooks can be executed on Read the Docs,
some of them take a very long time to run or
need special Docker environments to execute,
which goes beyond what the platform supports. In these cases I needed to check
executed notebooks (often with large images) into my git repository, causing
huge amounts of bloat. Futhermore, the executed notebooks would often get out of
sync with the development of the code.No more!!This library avoids these issues by executing code onGitHub
Actions, uploading build artifacts (in
this case, executed Jupter notebooks), and then (only then!) triggering a
Read the Docs build that can download the executed notebooks.There is still some work required to set up this workflow, but this library has
three pieces that make it a bit easier:A GitHub action that can be used to trigger a build for the current branch on
Read the Docs.A Sphinx extension that interfaces with the GitHub API to download the
artifact produced for the target commit hash.Some documentation that shows you how to set all this up!UsageThe following gives the detailed steps of the process of setting up a project
using this workflow. But you can also see a fully functional example in this
repository. The documentation source is thedocsdirectory and the.github/workflowsdirectory includes a workflow that is executed to build the
docs using this package. The rendered page is available atrtds-action.readthedocs.io.1. Set up Read the DocsFirst, you'll need to import your project as usual. If you've already done
that, don't worry: this will also work with existing Read the Docs projects.Next, go to the admin page for your project on Read the Docs, click onIntegrations(the URL is something likehttps://readthedocs.org/dashboard/YOUR_PROJECT_NAME/integrations/).ClickAdd integrationand selectGeneric API incoming webhook.Take note of the webhookURLandtokenon this page for use later.You should also edit your webhook settings on GitHub by going tohttps://github.com/USERNAME/REPONAME/settings/hooksand clicking "Edit"
next to the Read the Docs hook. On that page, you should un-check thePushesoption.2. Set up GitHub Actions workflowIn this example, we'll assume that we have tutorials written as Jupyter
notebooks, saved as Python scripts usingJupytext(because
that's probably what you should be doing anyways!) in a directory calleddocs/tutorials.First, you'll need to add the Read the Docs webhook URL and token that you
recorded above as "secrets" for your GitHub project by going to the URLhttps://github.com/USERNAME/REPONAME/settings/secrets. I'll call themRTDS_WEBHOOK_URL(include thehttps!) andRTDS_WEBHOOK_TOKENrespectively.For this use case, we can create the workflow.github/workflows/docs.ymlas
follows:name:Docson:[push,release]jobs:notebooks:name:"Buildthenotebooksforthedocs"runs-on:ubuntu-lateststeps:-uses:actions/checkout@v2-name:Set up Pythonuses:actions/setup-python@v2with:python-version:3.8-name:Install dependenciesrun:|python -m pip install -U pippython -m pip install -r .github/workflows/requirements.txt-name:Execute the notebooksrun:|jupytext --to ipynb --execute docs/tutorials/*.py-uses:actions/upload-artifact@v2with:name:notebooks-for-${{ github.sha }}path:docs/tutorials-name:Trigger RTDs builduses:dfm/rtds-action@v1with:webhook_url:${{ secrets.RTDS_WEBHOOK_URL }}webhook_token:${{ secrets.RTDS_WEBHOOK_TOKEN }}commit_ref:${{ github.ref }}Here, we're also assuming that we've added apiprequirements file at.github/workflows/requirements.txtwith the dependencies required to execute
the notebooks. Also note that in theupload-artifactstep we give our artifact
that depends on the hash of the current commit. This is crucial! We also need to
take note of thenotebooks-for-prefix because we'll use that later.It's worth emphasizing here that the only "special" steps in this workflow are
the last two. You can do whatever you want to generate your artifact in the
previous steps (for example, you could usecondainstead ofpip) because
this workflow is not picky about how you get there!3. Set up SphinxFinally, you can edit theconf.pyfor your Sphinx documentation to add support
for fetching the artifact produced by your action. Here is a minimal example:importosextensions=[..."rtds_action"]# The name of your GitHub repositoryrtds_action_github_repo="USERNAME/REPONAME"# The path where the artifact should be extracted# Note: this is relative to the conf.py file!rtds_action_path="tutorials"# The "prefix" used in the `upload-artifact` step of the actionrtds_action_artifact_prefix="notebooks-for-"# A GitHub personal access token is required, more info belowrtds_action_github_token=os.environ["GITHUB_TOKEN"]# Whether or not to raise an error on Read the Docs if the# artifact containing the notebooks can't be downloaded (optional)rtds_action_error_if_missing=FalseWhere we have added the custom extension and set the required configuration
parameters.You'll need to provide Read the Docs with a GitHub personal access token (it only
needs thepublic_reposcope if your repo is public). You can generate a new
token by going toyour GitHub settings
page. Then, save it as an environment
variable (calledGITHUB_TOKENin this case) on Read the Docs.DevelopmentFor now, just a note: if you editsrc/js/index.js, youmustrunnpm run packageto generate the compiled action source.