# Interface Read the Docs and GitHub Actions
[](https://github.com/dfm/rtds-action/actions?query=workflow%3ADocs)
[](https://rtds-action.readthedocs.io/en/latest/?badge=latest)
I like to use [Read the Docs](https://readthedocs.org/) to build (and version!) my
docs, but I _also_ like to use [Jupyter notebooks](https://jupyter.org/) to
write tutorials. Unfortunately, even though
[notebooks can be executed on Read the Docs](https://docs.readthedocs.io/en/stable/guides/jupyter.html),
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](https://github.com/features/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:
1. A GitHub action that can be used to trigger a build for the current branch on
Read the Docs.
2. A Sphinx extension that interfaces with the GitHub API to download the
artifact produced for the target commit hash.
3. 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](https://rtds-action.readthedocs.io).
### 1. Set up Read the Docs
1. 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.
2. 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/`).
3. Click `Add integration` and select `Generic API incoming webhook`.
4. 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](https://jupytext.readthedocs.io/en/latest/introduction.html) (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/checkout@v2
- name: Set up Python
uses: actions/setup-python@v2
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/upload-artifact@v2
with:
name: notebooks-for-${{ github.sha }}
path: docs/tutorials
- name: Trigger RTDs build
uses: dfm/rtds-action@v1
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](https://github.com/settings/tokens). 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.
Raw data
{
"_id": null,
"home_page": "https://github.com/dfm/rtds-action",
"name": "rtds-action",
"maintainer": "Daniel Foreman-Mackey",
"docs_url": null,
"requires_python": "",
"maintainer_email": "foreman.mackey@gmail.com",
"keywords": "",
"author": "Daniel Foreman-Mackey",
"author_email": "foreman.mackey@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/e5/f2/d6b99748e97ba132f856f1caa891d577da63bacb44a08eb4944e6511c986/rtds_action-1.1.0.tar.gz",
"platform": null,
"description": "# Interface Read the Docs and GitHub Actions\n\n[](https://github.com/dfm/rtds-action/actions?query=workflow%3ADocs)\n[](https://rtds-action.readthedocs.io/en/latest/?badge=latest)\n\nI like to use [Read the Docs](https://readthedocs.org/) to build (and version!) my\ndocs, but I _also_ like to use [Jupyter notebooks](https://jupyter.org/) to\nwrite tutorials. Unfortunately, even though\n[notebooks can be executed on Read the Docs](https://docs.readthedocs.io/en/stable/guides/jupyter.html),\nsome of them take a very long time to run or\nneed special Docker environments to execute,\nwhich goes beyond what the platform supports. In these cases I needed to check\nexecuted notebooks (often with large images) into my git repository, causing\nhuge amounts of bloat. Futhermore, the executed notebooks would often get out of\nsync with the development of the code. **No more!!**\n\n_This library avoids these issues by executing code on [GitHub\nActions](https://github.com/features/actions), uploading build artifacts (in\nthis case, executed Jupter notebooks), and then (only then!) triggering a\nRead the Docs build that can download the executed notebooks._\n\nThere is still some work required to set up this workflow, but this library has\nthree pieces that make it a bit easier:\n\n1. A GitHub action that can be used to trigger a build for the current branch on\n Read the Docs.\n2. A Sphinx extension that interfaces with the GitHub API to download the\n artifact produced for the target commit hash.\n3. Some documentation that shows you how to set all this up!\n\n## Usage\n\nThe following gives the detailed steps of the process of setting up a project\nusing this workflow. But you can also see a fully functional example in this\nrepository. The documentation source is the `docs` directory and the\n`.github/workflows` directory includes a workflow that is executed to build the\ndocs using this package. The rendered page is available at\n[rtds-action.readthedocs.io](https://rtds-action.readthedocs.io).\n\n### 1. Set up Read the Docs\n\n1. First, you'll need to import your project as usual. If you've already done\n that, don't worry: this will also work with existing Read the Docs projects.\n2. Next, go to the admin page for your project on Read the Docs, click on\n `Integrations` (the URL is something like\n `https://readthedocs.org/dashboard/YOUR_PROJECT_NAME/integrations/`).\n3. Click `Add integration` and select `Generic API incoming webhook`.\n4. Take note of the webhook `URL` and `token` on this page for use later.\n\nYou should also edit your webhook settings on GitHub by going to\n`https://github.com/USERNAME/REPONAME/settings/hooks` and clicking \"Edit\"\nnext to the Read the Docs hook. On that page, you should un-check the `Pushes`\noption.\n\n### 2. Set up GitHub Actions workflow\n\nIn this example, we'll assume that we have tutorials written as Jupyter\nnotebooks, saved as Python scripts using\n[Jupytext](https://jupytext.readthedocs.io/en/latest/introduction.html) (because\nthat's probably what you should be doing anyways!) in a directory called\n`docs/tutorials`.\n\nFirst, you'll need to add the Read the Docs webhook URL and token that you\nrecorded above as \"secrets\" for your GitHub project by going to the URL\n`https://github.com/USERNAME/REPONAME/settings/secrets`. I'll call them\n`RTDS_WEBHOOK_URL` (include the `https`!) and `RTDS_WEBHOOK_TOKEN` respectively.\n\nFor this use case, we can create the workflow `.github/workflows/docs.yml` as\nfollows:\n\n```yaml\nname: Docs\non: [push, release]\n\njobs:\n notebooks:\n name: \"Build the notebooks for the docs\"\n runs-on: ubuntu-latest\n steps:\n - uses: actions/checkout@v2\n\n - name: Set up Python\n uses: actions/setup-python@v2\n with:\n python-version: 3.8\n\n - name: Install dependencies\n run: |\n python -m pip install -U pip\n python -m pip install -r .github/workflows/requirements.txt\n\n - name: Execute the notebooks\n run: |\n jupytext --to ipynb --execute docs/tutorials/*.py\n\n - uses: actions/upload-artifact@v2\n with:\n name: notebooks-for-${{ github.sha }}\n path: docs/tutorials\n\n - name: Trigger RTDs build\n uses: dfm/rtds-action@v1\n with:\n webhook_url: ${{ secrets.RTDS_WEBHOOK_URL }}\n webhook_token: ${{ secrets.RTDS_WEBHOOK_TOKEN }}\n commit_ref: ${{ github.ref }}\n```\n\nHere, we're also assuming that we've added a `pip` requirements file at\n`.github/workflows/requirements.txt` with the dependencies required to execute\nthe notebooks. Also note that in the `upload-artifact` step we give our artifact\nthat depends on the hash of the current commit. This is crucial! We also need to\ntake note of the `notebooks-for-` prefix because we'll use that later.\n\nIt's worth emphasizing here that the only \"special\" steps in this workflow are\nthe last two. You can do whatever you want to generate your artifact in the\nprevious steps (for example, you could use `conda` instead of `pip`) because\nthis workflow is not picky about how you get there!\n\n### 3. Set up Sphinx\n\nFinally, you can edit the `conf.py` for your Sphinx documentation to add support\nfor fetching the artifact produced by your action. Here is a minimal example:\n\n```python\nimport os\n\nextensions = [... \"rtds_action\"]\n\n# The name of your GitHub repository\nrtds_action_github_repo = \"USERNAME/REPONAME\"\n\n# The path where the artifact should be extracted\n# Note: this is relative to the conf.py file!\nrtds_action_path = \"tutorials\"\n\n# The \"prefix\" used in the `upload-artifact` step of the action\nrtds_action_artifact_prefix = \"notebooks-for-\"\n\n# A GitHub personal access token is required, more info below\nrtds_action_github_token = os.environ[\"GITHUB_TOKEN\"]\n\n# Whether or not to raise an error on Read the Docs if the\n# artifact containing the notebooks can't be downloaded (optional)\nrtds_action_error_if_missing = False\n```\n\nWhere we have added the custom extension and set the required configuration\nparameters.\n\nYou'll need to provide Read the Docs with a GitHub personal access token (it only\nneeds the `public_repo` scope if your repo is public). You can generate a new\ntoken by going to [your GitHub settings\npage](https://github.com/settings/tokens). Then, save it as an environment\nvariable (called `GITHUB_TOKEN` in this case) on Read the Docs.\n\n## Development\n\nFor now, just a note: if you edit `src/js/index.js`, you _must_ run `npm run package` to generate the compiled action source.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Interface GitHub Actions and ReadTheDocs",
"version": "1.1.0",
"project_urls": {
"Homepage": "https://github.com/dfm/rtds-action"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "4054b9aaf8e4867e95ac8ea27cd3249946c62c58058779e998040442d6d07625",
"md5": "abc76239a074352d2e6d34c2d586c3fe",
"sha256": "097a73eac507387a32b24c3da690f3a876936cb56150aa1786d52a9a67cd62f9"
},
"downloads": -1,
"filename": "rtds_action-1.1.0-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "abc76239a074352d2e6d34c2d586c3fe",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": null,
"size": 6660,
"upload_time": "2023-06-01T11:44:33",
"upload_time_iso_8601": "2023-06-01T11:44:33.475512Z",
"url": "https://files.pythonhosted.org/packages/40/54/b9aaf8e4867e95ac8ea27cd3249946c62c58058779e998040442d6d07625/rtds_action-1.1.0-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "e5f2d6b99748e97ba132f856f1caa891d577da63bacb44a08eb4944e6511c986",
"md5": "bb99fd1d62db17071a23adfab5443feb",
"sha256": "f824851318a5d41550ae30edfb166dc6442bc9b9940a50ea06e649cd471f6ac1"
},
"downloads": -1,
"filename": "rtds_action-1.1.0.tar.gz",
"has_sig": false,
"md5_digest": "bb99fd1d62db17071a23adfab5443feb",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 81459,
"upload_time": "2023-06-01T11:44:34",
"upload_time_iso_8601": "2023-06-01T11:44:34.680209Z",
"url": "https://files.pythonhosted.org/packages/e5/f2/d6b99748e97ba132f856f1caa891d577da63bacb44a08eb4944e6511c986/rtds_action-1.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-06-01 11:44:34",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "dfm",
"github_project": "rtds-action",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "rtds-action"
}
JSON
