From 5272cd8a71c54c6366d0d60bc0f854a6d8034a7b Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Fri, 14 Feb 2025 16:59:47 +0100 Subject: [PATCH] Added pull request build --- book/_toc.yml | 1 + book/features/pull_request_build.md | 56 +++++++++++++++++++++++++++++ requirements.txt | 2 +- 3 files changed, 58 insertions(+), 1 deletion(-) create mode 100644 book/features/pull_request_build.md diff --git a/book/_toc.yml b/book/_toc.yml index 002dfcb..aa5ee76 100644 --- a/book/_toc.yml +++ b/book/_toc.yml @@ -53,6 +53,7 @@ parts: - file: external/template/README.md - file: features/teachbooks - file: external/deploy-book-workflow/README.md + - file: features/pull_requests_build.md - file: features/local_server - file: external/Nested-Books/README.md - file: features/update_env diff --git a/book/features/pull_request_build.md b/book/features/pull_request_build.md new file mode 100644 index 0000000..b9da97e --- /dev/null +++ b/book/features/pull_request_build.md @@ -0,0 +1,56 @@ +# Build pull requests + +```{admonition} User types +:class: tip +This section is useful for user type 3-5. +``` + +When using the [deploy-book-workflow](../external/deploy-book-workflow/README.md) you're not able to build pull requests. When you'd like to contribute to the book of someone else with a fork, this requires you to set up the deploy-book-workflow in your fork to be able to show the proposed changes in the book. Furthermore, when proposing your contribution in a pull-request, you'd have to manually refer to your own built book. This process can be made easier by using [Read the Docs](https://about.readthedocs.com/?ref=readthedocs.org) for building the books with changes of a pull request. + +Read the docs is not recommended for final versions of your book because of the advertisement in the free version. + +## Setting up building of pull-requests + +### Add configuration file to your repository + +Add a file `.readthedocs.yaml` to the root of your repository, containing the following content: + +```yaml +version: 2 + +build: + os: ubuntu-24.04 + tools: + python: "3.13" + jobs: + pre_build: + - "jupyter-book config sphinx book/" + +python: + install: + - requirements: requirements.txt + +sphinx: + builder: html + fail_on_warning: true + configuration: book/conf.py +``` + +You might need to add `imghdr` to your `requirements.txt` file if the build fails when you've configured it in Read the Docs (if the error tells you `ModuleNotFoundError: No module named 'imghdr'`) + +### Setup Read The Docs account + +Setup an account at [](https://app.readthedocs.org/accounts/login/?next=/dashboard/). We recommend using your GitHub account for authentication. + +When authorizing Read the Docs for your GitHub account, you can grant access by Read the Docs for organization you own too. Do this if your book is part of an organization. + +### Authorize access to organization +When you didn't do so in the previous step, or you'd like to grant access at a later moment, you can grant/revoke access by Read the Docs to organization your own [`personal GitHub Settings - Integrations - Applications - Authorized OAuth Apps - Read the Docs Community`](https://github.com/settings/connections/applications/fae83c942bc1d89609e2). + +### Add project in Read The Docs + +On your [dashboard](https://app.readthedocs.org/dashboard/), add a new project. Find your GitHub repository (you might need to refresh your repositories if you've recently updated authorizations) + +### Enable Pull Request build + +In the setting of your newest project, enable build of pull request by selecting the option in `Building - Pull request builds - Build pull requests for this project`. \ No newline at end of file diff --git a/requirements.txt b/requirements.txt index 065c5e5..f35fdc5 100644 --- a/requirements.txt +++ b/requirements.txt @@ -8,9 +8,9 @@ sphinx-image-inverter == 1.1.0 sphinx-exercise == 1.0.1 sphinx-proof == 0.2.0 sphinx-named-colors == 1.0.1 +imghdr --extra-index-url https://gitlab.tudelft.nl/api/v4/projects/11239/packages/pypi/simple sphinx-thebe ~= 0.9.9 docutils==0.17.1 -