Interface ReadTheDocs and GitHub Actions

dfm, updated 🕥 2022-08-18 19:29:59

Interface Read the Docs and GitHub Actions

I like to use Read the Docs to build (and version!) my docs, but I also like to use Jupyter notebooks to write tutorials. Unfortunately, even though notebooks 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 on GitHub 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!

Usage

The 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 the docs directory and the .github/workflows directory includes a workflow that is executed to build the docs using this package. The rendered page is available at rtds-action.readthedocs.io.

1. Set up Read the Docs

First, 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 on Integrations (the URL is something like https://readthedocs.org/dashboard/YOUR_PROJECT_NAME/integrations/).
Click Add integration and select Generic API incoming webhook.
Take note of the webhook URL and token on this page for use later.

You should also edit your webhook settings on GitHub by going to https://github.com/USERNAME/REPONAME/settings/hooks and clicking "Edit" next to the Read the Docs hook. On that page, you should un-check the Pushes option.

2. Set up GitHub Actions workflow

In this example, we'll assume that we have tutorials written as Jupyter notebooks, saved as Python scripts using Jupytext (because that's probably what you should be doing anyways!) in a directory called docs/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 URL https://github.com/USERNAME/REPONAME/settings/secrets. I'll call them RTDS_WEBHOOK_URL (include the https!) and RTDS_WEBHOOK_TOKEN respectively.

For this use case, we can create the workflow .github/workflows/docs.yml as follows:

```yaml name: Docs on: [push, release]

jobs: notebooks: name: "Build the notebooks for the docs" runs-on: ubuntu-latest steps: - uses: actions/[email protected]

  - name: Set up Python
    uses: actions/[email protected]
    with:
      python-version: 3.8

  - name: Install dependencies
    run: |
      python -m pip install -U pip
      python -m pip install -r .github/workflows/requirements.txt

  - name: Execute the notebooks
    run: |
      jupytext --to ipynb --execute docs/tutorials/*.py

  - uses: actions/[email protected]
    with:
      name: notebooks-for-${{ github.sha }}
      path: docs/tutorials

  - name: Trigger RTDs build
    uses: dfm/[email protected]
    with:
      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 a pip requirements file at .github/workflows/requirements.txt with the dependencies required to execute the notebooks. Also note that in the upload-artifact step we give our artifact that depends on the hash of the current commit. This is crucial! We also need to take note of the notebooks-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 use conda instead of pip) because this workflow is not picky about how you get there!

3. Set up Sphinx

Finally, you can edit the conf.py for your Sphinx documentation to add support for fetching the artifact produced by your action. Here is a minimal example:

```python import os

extensions = [... "rtds_action"]

The name of your GitHub repository

rtds_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 action

rtds_action_artifact_prefix = "notebooks-for-"

A GitHub personal access token is required, more info below

rtds_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 = False ```

Where 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 the public_repo scope if your repo is public). You can generate a new token by going to your GitHub settings page. Then, save it as an environment variable (called GITHUB_TOKEN in this case) on Read the Docs.

Development

For now, just a note: if you edit src/js/index.js, you must run npm run package to generate the compiled action source.

Issues

Action runs but does not trigger build

opened on 2023-03-10 10:04:40 by jobrachem

We are using the rtds-action in the CI of our project to render some .qmd tutorial files before building the documentation. A few days ago, everything worked as expected.

Now, while the weebhook does still reach readthedocs, it does not trigger a build:

{ "build_triggered": false, "project": "liesel", "versions": [] }

I am at a loss in terms of how to debug this - and I don't know whether it's a user-problem or a bug in the action. We observed this the first time after we made a new release on GitHub. Would be thankful for some guidance.

Bump @actions/core from 1.2.6 to 1.9.1

opened on 2022-08-18 19:29:59 by dependabot[bot]

Bumps @actions/core from 1.2.6 to 1.9.1.

Changelog

Sourced from @actions/core's changelog.

1.9.1

Randomize delimiter when calling core.exportVariable

1.9.0

Added toPosixPath, toWin32Path and toPlatformPath utilities #1102

1.8.2

Update to v2.0.1 of @actions/http-client #1087

1.8.1

Update to v2.0.0 of @actions/http-client

1.8.0

Deprecate markdownSummary extension export in favor of summary

actions/toolkit#1072

actions/toolkit#1073

1.7.0

Added markdownSummary extension

1.6.0

Added OIDC Client function getIDToken

Added file parameter to AnnotationProperties

1.5.0

Added support for notice annotations and more annotation fields

1.4.0

Added the getMultilineInput function

1.3.0

Added the trimWhitespace option to getInput

Added the getBooleanInput function

1.2.7

Prepend newline for set-output

Commits

See full diff in compare view

Dependabot will resolve any conflicts with this PR as long as you don't alter it yourself. You can also trigger a rebase manually by commenting @dependabot rebase.

Dependabot commands and options

You can trigger Dependabot actions by commenting on this PR: - `@dependabot rebase` will rebase this PR - `@dependabot recreate` will recreate this PR, overwriting any edits that have been made to it - `@dependabot merge` will merge this PR after your CI passes on it - `@dependabot squash and merge` will squash and merge this PR after your CI passes on it - `@dependabot cancel merge` will cancel a previously requested merge and block automerging - `@dependabot reopen` will reopen this PR if it is closed - `@dependabot close` will close this PR and stop Dependabot recreating it. You can achieve the same result by closing it manually - `@dependabot ignore this major version` will close this PR and stop Dependabot creating any more for this major version (unless you reopen the PR or upgrade to it yourself) - `@dependabot ignore this minor version` will close this PR and stop Dependabot creating any more for this minor version (unless you reopen the PR or upgrade to it yourself) - `@dependabot ignore this dependency` will close this PR and stop Dependabot creating any more for this dependency (unless you reopen the PR or upgrade to it yourself) - `@dependabot use these labels` will set the current labels as the default for future PRs for this repo and language - `@dependabot use these reviewers` will set the current reviewers as the default for future PRs for this repo and language - `@dependabot use these assignees` will set the current assignees as the default for future PRs for this repo and language - `@dependabot use this milestone` will set the current milestone as the default for future PRs for this repo and language You can disable automated security fix PRs for this repo from the [Security Alerts page](https://github.com/dfm/rtds-action/network/alerts).

What are RTDS_WEBHOOK_URL and RTDS_WEBHOOK_TOKEN

opened on 2022-07-15 10:10:43 by ale94mleon

Hi, I am trying to setup this action but i don't get what are the secrets to use. I went to integration on readthedoc and I only see one url: https://readthedocs.org/api/v2/webhook/my_packege_name/a_number/ Is: RTDS_WEBHOOK_URL = https://readthedocs.org/api/v2/webhook/my_packege_name/ and RTDS_WEBHOOK_TOKEN = a_number? Thanks in advance!

invalid json response error

opened on 2022-06-15 18:53:17 by phildong

Hello, I'm getting the following error on an action run recently. Seems there might be some API change on rtd side? Let me know if I can provide more info!

Run dfm/[email protected] with: webhook_url: *** webhook_token: *** commit_ref: refs/pull/207/merge env: CONDA_PKGS_DIR: /home/runner/conda_pkgs_dir Error: invalid json response body at *** reason: Unexpected token < in JSON at position 0

Support auto-building PR docs

opened on 2020-09-08 18:54:14 by jdhughes-usgs

Have been successfully using rtds-action for a few repos but for some reason the rtds is not being triggered on one of the repos now. I haven't been able to identify anything obvious. I have reset the Generic API incoming webhook on rtds and the secrets on github.

I noticed that the latest Docs action on rtds-action had the same message "build_triggered: false".

Not sure if this is a rtds-action or rtd issue. Any idea?

Releases

rtds-action v1.0.3 2021-02-24 23:00:14

Adds rtds_action_error_if_missing option

rtds-action v1.0.2 2020-09-24 17:17:25

Bugfix for 1.0.1

rtds-action v1.0.1 2020-09-24 16:56:25

Adding re-tries to Python module
Update dependencies

rtds-action v1.0.0 2020-07-22 14:49:38

Initial "stable" release

rtds-action v1.0.0rc4 2020-07-22 14:44:19

Another try!

rtds-action v1.0.0rc3 2020-07-22 14:18:45

Another try after updating hooks

Dan Foreman-Mackey

GitHub Repository Homepage