From 5272cd8a71c54c6366d0d60bc0f854a6d8034a7b Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Fri, 14 Feb 2025 16:59:47 +0100 Subject: [PATCH 01/19] 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 - From 908e017a40a718b550e4c3d915799913431d8c2c Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Fri, 14 Feb 2025 17:01:42 +0100 Subject: [PATCH 02/19] WIP --- book/features/pull_request_build.md | 2 +- requirements.txt | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/book/features/pull_request_build.md b/book/features/pull_request_build.md index b9da97e..d90a203 100644 --- a/book/features/pull_request_build.md +++ b/book/features/pull_request_build.md @@ -36,7 +36,7 @@ sphinx: 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'`) +You might need to add `standard-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 diff --git a/requirements.txt b/requirements.txt index f35fdc5..4d3ea2c 100644 --- a/requirements.txt +++ b/requirements.txt @@ -8,7 +8,7 @@ sphinx-image-inverter == 1.1.0 sphinx-exercise == 1.0.1 sphinx-proof == 0.2.0 sphinx-named-colors == 1.0.1 -imghdr +standard-imghdr --extra-index-url https://gitlab.tudelft.nl/api/v4/projects/11239/packages/pypi/simple sphinx-thebe ~= 0.9.9 From def4fb764b7bdcffe66a81fb27792b63c81ffb8a Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Fri, 14 Feb 2025 17:19:00 +0100 Subject: [PATCH 03/19] WIP --- book/features/figures/readthedocs1.png | Bin 0 -> 30722 bytes book/features/pull_request_build.md | 18 +++++++++++++++--- 2 files changed, 15 insertions(+), 3 deletions(-) create mode 100644 book/features/figures/readthedocs1.png diff --git a/book/features/figures/readthedocs1.png b/book/features/figures/readthedocs1.png new file mode 100644 index 0000000000000000000000000000000000000000..f1d8d493f7f2a5e35955d1b1d9f2e642dd1b1654 GIT binary patch literal 30722 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 literal 0 HcmV?d00001 diff --git a/book/features/pull_request_build.md b/book/features/pull_request_build.md index d90a203..6697d9a 100644 --- a/book/features/pull_request_build.md +++ b/book/features/pull_request_build.md @@ -9,6 +9,8 @@ When using the [deploy-book-workflow](../external/deploy-book-workflow/README.md Read the docs is not recommended for final versions of your book because of the advertisement in the free version. +This workflow does not work if you have local sphinx extensions in your book (extensions in `book/_ext` like [](./apa.md)). + ## Setting up building of pull-requests ### Add configuration file to your repository @@ -24,11 +26,13 @@ build: python: "3.13" jobs: pre_build: + - "sed -i '/local_extensions:/,/^[^ ]/d' book/_config.yml" - "jupyter-book config sphinx book/" python: install: - requirements: requirements.txt + - requirements: standard-imghdr sphinx: builder: html @@ -36,8 +40,6 @@ sphinx: configuration: book/conf.py ``` -You might need to add `standard-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. @@ -53,4 +55,14 @@ On your [dashboard](https://app.readthedocs.org/dashboard/), add a new project. ### 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 +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`. + +## Usage + +When opening a pull request, GitHub will shows this line: + +![Read the docs in GitHub preview](./figures/readthedocs1.png) + +Click 'Details' to see the logs of the build process. + +Whenever the build is done, c \ No newline at end of file From 01870a3122155fecebddbe671c2680a531ca0529 Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Fri, 14 Feb 2025 17:19:44 +0100 Subject: [PATCH 04/19] Update .readthedocs.yaml --- .readthedocs.yaml | 1 - 1 file changed, 1 deletion(-) diff --git a/.readthedocs.yaml b/.readthedocs.yaml index 27d35f2..54db7f1 100644 --- a/.readthedocs.yaml +++ b/.readthedocs.yaml @@ -12,7 +12,6 @@ build: python: install: - requirements: requirements.txt - - requirements: standard-imghdr sphinx: builder: html From 2a2a4a8fb207f9b2b2d08cca8907377422eed01e Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Fri, 14 Feb 2025 17:23:59 +0100 Subject: [PATCH 05/19] fix --- .readthedocs.yaml | 2 +- book/features/pull_request_build.md | 4 +++- 2 files changed, 4 insertions(+), 2 deletions(-) diff --git a/.readthedocs.yaml b/.readthedocs.yaml index 54db7f1..7ef772a 100644 --- a/.readthedocs.yaml +++ b/.readthedocs.yaml @@ -6,7 +6,7 @@ build: python: "3.13" jobs: pre_build: - - "sed -i '/local_extensions:/,/^[^ ]/d' book/_config.yml" + - "sed -i '\\/local_extensions:/,\\/^[^ ]/d' book/_config.yml" - "jupyter-book config sphinx book/" python: diff --git a/book/features/pull_request_build.md b/book/features/pull_request_build.md index 6697d9a..0cf1470 100644 --- a/book/features/pull_request_build.md +++ b/book/features/pull_request_build.md @@ -38,7 +38,9 @@ sphinx: builder: html fail_on_warning: true configuration: book/conf.py -``` + ``` + +You might need to add `standard-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 From 761821cfc0925def5777986bb424243423bb7404 Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Fri, 14 Feb 2025 17:25:06 +0100 Subject: [PATCH 06/19] typo --- book/_toc.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/_toc.yml b/book/_toc.yml index aa5ee76..86d7d0c 100644 --- a/book/_toc.yml +++ b/book/_toc.yml @@ -53,7 +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/pull_request_build.md - file: features/local_server - file: external/Nested-Books/README.md - file: features/update_env From 38e39a0357b750a8d960da8ab4901ece12a483df Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Fri, 14 Feb 2025 17:27:20 +0100 Subject: [PATCH 07/19] fix? --- .readthedocs.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.readthedocs.yaml b/.readthedocs.yaml index 7ef772a..dd75137 100644 --- a/.readthedocs.yaml +++ b/.readthedocs.yaml @@ -6,7 +6,7 @@ build: python: "3.13" jobs: pre_build: - - "sed -i '\\/local_extensions:/,\\/^[^ ]/d' book/_config.yml" + - "sed -i '\|local_extensions:|,\|^[^ ]|d' book/_config.yml" - "jupyter-book config sphinx book/" python: From 7f16b06b46b255574a4e4e89dfed74498312cd1b Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Fri, 14 Feb 2025 17:30:25 +0100 Subject: [PATCH 08/19] simplify --- .readthedocs.yaml | 19 ------------------- book/features/pull_request_build.md | 5 ++--- 2 files changed, 2 insertions(+), 22 deletions(-) delete mode 100644 .readthedocs.yaml diff --git a/.readthedocs.yaml b/.readthedocs.yaml deleted file mode 100644 index dd75137..0000000 --- a/.readthedocs.yaml +++ /dev/null @@ -1,19 +0,0 @@ -version: 2 - -build: - os: ubuntu-24.04 - tools: - python: "3.13" - jobs: - pre_build: - - "sed -i '\|local_extensions:|,\|^[^ ]|d' book/_config.yml" - - "jupyter-book config sphinx book/" - -python: - install: - - requirements: requirements.txt - -sphinx: - builder: html - fail_on_warning: true - configuration: book/conf.py diff --git a/book/features/pull_request_build.md b/book/features/pull_request_build.md index 0cf1470..18eba1f 100644 --- a/book/features/pull_request_build.md +++ b/book/features/pull_request_build.md @@ -1,4 +1,4 @@ -# Build pull requests +# Build pull requests from forks ```{admonition} User types :class: tip @@ -26,7 +26,6 @@ build: python: "3.13" jobs: pre_build: - - "sed -i '/local_extensions:/,/^[^ ]/d' book/_config.yml" - "jupyter-book config sphinx book/" python: @@ -67,4 +66,4 @@ When opening a pull request, GitHub will shows this line: Click 'Details' to see the logs of the build process. -Whenever the build is done, c \ No newline at end of file +Whenever the build is done, click 'Details' again to see the build book. Tip, click `d` or add `?readthedocs-diff=true` to the url to see the differences on the pages highlighted. Note that this difference functionality is not perfect as it might indicate elements which are not changed and it has issues with buttons, LaTeX and figures. \ No newline at end of file From 78f5f758321f6603c76995ca5a66f84710911b6a Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Fri, 14 Feb 2025 17:32:07 +0100 Subject: [PATCH 09/19] reorder --- book/features/pull_request_build.md | 26 +++++++++++++------------- 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/book/features/pull_request_build.md b/book/features/pull_request_build.md index 18eba1f..594c834 100644 --- a/book/features/pull_request_build.md +++ b/book/features/pull_request_build.md @@ -7,11 +7,21 @@ 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. +Read the docs is not recommended for final versions of your book because of the advertisement in the free version. if you'd like to pay for it, it can replace the functionality of the [deploy-book-workflow](../external/deploy-book-workflow/README.md). This workflow does not work if you have local sphinx extensions in your book (extensions in `book/_ext` like [](./apa.md)). -## Setting up building of pull-requests +## Usage + +When opening a pull request, GitHub will shows this line: + +![Read the docs in GitHub preview](./figures/readthedocs1.png) + +Click 'Details' to see the logs of the build process. + +Whenever the build is done, click 'Details' again to see the build book. Tip, click `d` or add `?readthedocs-diff=true` to the url to see the differences on the pages highlighted. Note that this difference functionality is not perfect as it might indicate elements which are not changed and it has issues with buttons, LaTeX and figures. + +## Setting up ### Add configuration file to your repository @@ -56,14 +66,4 @@ On your [dashboard](https://app.readthedocs.org/dashboard/), add a new project. ### 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`. - -## Usage - -When opening a pull request, GitHub will shows this line: - -![Read the docs in GitHub preview](./figures/readthedocs1.png) - -Click 'Details' to see the logs of the build process. - -Whenever the build is done, click 'Details' again to see the build book. Tip, click `d` or add `?readthedocs-diff=true` to the url to see the differences on the pages highlighted. Note that this difference functionality is not perfect as it might indicate elements which are not changed and it has issues with buttons, LaTeX and figures. \ No newline at end of file +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 From 1ef2704ceb3cb9151e8927e680df80e5565de74d Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Fri, 14 Feb 2025 17:36:17 +0100 Subject: [PATCH 10/19] typo --- book/features/pull_request_build.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/features/pull_request_build.md b/book/features/pull_request_build.md index 594c834..37478a7 100644 --- a/book/features/pull_request_build.md +++ b/book/features/pull_request_build.md @@ -7,7 +7,7 @@ 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. if you'd like to pay for it, it can replace the functionality of the [deploy-book-workflow](../external/deploy-book-workflow/README.md). +Read the docs is not recommended for final versions of your book because of the advertisement in the free version. If you'd like to pay for it, it can replace the functionality of the [deploy-book-workflow](../external/deploy-book-workflow/README.md). This workflow does not work if you have local sphinx extensions in your book (extensions in `book/_ext` like [](./apa.md)). From 392780a425a1f71b75a764160e4190fc640044c3 Mon Sep 17 00:00:00 2001 From: Robert Lanzafame Date: Sun, 16 Feb 2025 03:29:23 +0100 Subject: [PATCH 11/19] text updates --- book/features/pull_request_build.md | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/book/features/pull_request_build.md b/book/features/pull_request_build.md index 37478a7..bae57b5 100644 --- a/book/features/pull_request_build.md +++ b/book/features/pull_request_build.md @@ -5,7 +5,7 @@ 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. +When using the [deploy-book-workflow](../external/deploy-book-workflow/README.md) you're not able to build pull requests from a fork of your repository (i.e., if someone makes a contribution to your book from a fork). 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 (e.g., with a hyperlink). This process can be made easier by using [Read the Docs](https://about.readthedocs.com/?ref=readthedocs.org), as it can automatically build a book based on changes proposed in a pull request. Read the docs is not recommended for final versions of your book because of the advertisement in the free version. If you'd like to pay for it, it can replace the functionality of the [deploy-book-workflow](../external/deploy-book-workflow/README.md). @@ -13,7 +13,7 @@ This workflow does not work if you have local sphinx extensions in your book (ex ## Usage -When opening a pull request, GitHub will shows this line: +When opening a pull request, GitHub will show this line: ![Read the docs in GitHub preview](./figures/readthedocs1.png) @@ -53,16 +53,17 @@ You might need to add `standard-imghdr` to your `requirements.txt` file if the b ### 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. +Setup an account at [app.readthedocs.org/accounts/login/](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. +When authorizing Read the Docs for your GitHub account, you can also grant access by Read the Docs for an organization of which you are an owner, as well, which we also recommend. ### 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). + +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 your organization by following these menu items in settings: [`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) +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 From e5259fdeb693660e4da79ea003f08638a0e63c05 Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Mon, 17 Feb 2025 07:41:41 +0100 Subject: [PATCH 12/19] Add more recommended settings --- book/features/pull_request_build.md | 15 ++++++++++++++- 1 file changed, 14 insertions(+), 1 deletion(-) diff --git a/book/features/pull_request_build.md b/book/features/pull_request_build.md index bae57b5..5b0566e 100644 --- a/book/features/pull_request_build.md +++ b/book/features/pull_request_build.md @@ -67,4 +67,17 @@ On your [dashboard](https://app.readthedocs.org/dashboard/), add a new project. ### 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 +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`. + +### Additional settings + +The following settings are recommended: +- `Setup` - `Settings` - `URL versioning scheme` - `Multiple versions without translations (//)`, as translated books can be implemented with [](../external/Sphinx-launch-buttons/README.md) +- `Setup` - `Settings` - `Addons` - `Search` - disabled, as your books already contain a search function and the Read the Docs search functions requires [additional setup](https://docs.readthedocs.com/platform/stable/intro/sphinx.html#configure-read-the-docs-search) +- `Setup` - `Settings` - `Addons` - `Link previews` - disabled, `Multiple versions without translations (//)`, as previews can be implemented with [](../external/teachbooks-sphinx-tippy/README.md) +- `Setup` - `Settings` - `Automation rules` - `Add rule`, to build all tagged versions of your book: + - `Description`: 'Build all tags' + - `Match`: `Custom Match` + - `Custom match`: `.*` + - `Version type`: `Tag` + - `Action`: `Activate version` From d2ff971d3610050ef2d1240a0a11374bdaf57a09 Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Mon, 17 Feb 2025 07:49:55 +0100 Subject: [PATCH 13/19] Added link to example book --- book/features/pull_request_build.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/book/features/pull_request_build.md b/book/features/pull_request_build.md index 5b0566e..f3955a5 100644 --- a/book/features/pull_request_build.md +++ b/book/features/pull_request_build.md @@ -21,6 +21,11 @@ Click 'Details' to see the logs of the build process. Whenever the build is done, click 'Details' again to see the build book. Tip, click `d` or add `?readthedocs-diff=true` to the url to see the differences on the pages highlighted. Note that this difference functionality is not perfect as it might indicate elements which are not changed and it has issues with buttons, LaTeX and figures. +### Example +As an example, Read the Docs is configured in this [example book](https://github.com/TeachBooks/Read-the-Docs-example-book). Fork it and open a pull request to test it's functionality. + +There's an example [pull request](https://github.com/TeachBooks/Read-the-Docs-example-book/pull/1) with corresponding [built book on Read the Docs](https://read-the-docs-example-book--1.org.readthedocs.build/1/intro2.html?readthedocs-diff=true). + ## Setting up ### Add configuration file to your repository From 3cac83be45c4b7b95a60a158f2becd00ac2518db Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Mon, 17 Feb 2025 08:01:46 +0100 Subject: [PATCH 14/19] revert requirements.txt --- requirements.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/requirements.txt b/requirements.txt index e879897..d975bba 100644 --- a/requirements.txt +++ b/requirements.txt @@ -7,9 +7,9 @@ sphinx-image-inverter == 1.1.0 sphinx-exercise == 1.0.1 sphinx-proof == 0.2.0 sphinx-named-colors == 1.0.1 -standard-imghdr --extra-index-url https://gitlab.tudelft.nl/api/v4/projects/11239/packages/pypi/simple sphinx-thebe ~= 0.9.9 docutils==0.17.1 + From e1f700ad5fc260cc0dc5b2ac93519599cc61d92a Mon Sep 17 00:00:00 2001 From: Robert Lanzafame Date: Mon, 17 Feb 2025 10:17:57 +0100 Subject: [PATCH 15/19] update description --- book/features/pull_request_build.md | 16 +++++++++++++--- 1 file changed, 13 insertions(+), 3 deletions(-) diff --git a/book/features/pull_request_build.md b/book/features/pull_request_build.md index f3955a5..ace1e87 100644 --- a/book/features/pull_request_build.md +++ b/book/features/pull_request_build.md @@ -5,21 +5,29 @@ 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 from a fork of your repository (i.e., if someone makes a contribution to your book from a fork). 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 (e.g., with a hyperlink). This process can be made easier by using [Read the Docs](https://about.readthedocs.com/?ref=readthedocs.org), as it can automatically build a book based on changes proposed in a pull request. +When writing a TeachBook it is useful to automatically build and view these changes online. This exactly why we designed and build the [deploy-book-workflow](../external/deploy-book-workflow/README.md) tool, which also allows for multiple versions of your book to exist at any time with customizable URL's. However, it doesn't cover all use cases. Luckily, Read the Docs is a free tool that can easily be used for this purpose! + +Pull Requests are a key tool for allowing anyone with a GitHub account to make a contribution to your work by forking your repository, adding commits, then sending them back to your repository via a Pull Request. Unfortunately you are not able to automatically build the book based on proposed changes in a pull request from a fork of your repository, as this requires the deploy-book-workflow in the fork to have GitHub Actions enabled 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 (e.g., with a hyperlink). This process can be made easier by using [Read the Docs](https://about.readthedocs.com/?ref=readthedocs.org), as it can automatically build a book based on changes proposed in a pull request, and includes a link to the book directly in the pull request page. Read the docs is not recommended for final versions of your book because of the advertisement in the free version. If you'd like to pay for it, it can replace the functionality of the [deploy-book-workflow](../external/deploy-book-workflow/README.md). This workflow does not work if you have local sphinx extensions in your book (extensions in `book/_ext` like [](./apa.md)). +```{tip} +Once set up, this tool is only accessible via the Pull Request page for a repository in the 'Checks' part of the automated rule set box (illustrated below). This is different from our deploy-book-workflow, which is accessed + +A Read the Docs account and admin privelages for the repository are only needed set this up; all visitors to the pull request page will be able to view the book, including the differencing feature. +``` + ## Usage -When opening a pull request, GitHub will show this line: +After visiting the summary page of a pull request you will be able to see the following line (_make sure you click "show all checks" to see it!_): ![Read the docs in GitHub preview](./figures/readthedocs1.png) Click 'Details' to see the logs of the build process. -Whenever the build is done, click 'Details' again to see the build book. Tip, click `d` or add `?readthedocs-diff=true` to the url to see the differences on the pages highlighted. Note that this difference functionality is not perfect as it might indicate elements which are not changed and it has issues with buttons, LaTeX and figures. +Whenever the build is done, click 'Details' again to see the build book. Tip, click `d` or add `?readthedocs-diff=true` to the url to see the differences on the pages highlighted. Note that this differencing functionality is not perfect as it might indicate elements which are not changed intentionally. It is known to have issues visualizing changes associated with buttons, LaTeX and figures. ### Example As an example, Read the Docs is configured in this [example book](https://github.com/TeachBooks/Read-the-Docs-example-book). Fork it and open a pull request to test it's functionality. @@ -28,6 +36,8 @@ There's an example [pull request](https://github.com/TeachBooks/Read-the-Docs-ex ## Setting up +This tool is a specific automation rule that is enabled within the GitHub pull request ecosystem. + ### Add configuration file to your repository Add a file `.readthedocs.yaml` to the root of your repository, containing the following content: From 76a13f169b5ceffef66d70a2310a7179f5cc7b90 Mon Sep 17 00:00:00 2001 From: Robert Lanzafame Date: Mon, 17 Feb 2025 10:25:08 +0100 Subject: [PATCH 16/19] add differencing feature to first paragraph --- book/features/pull_request_build.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/features/pull_request_build.md b/book/features/pull_request_build.md index ace1e87..37aaec9 100644 --- a/book/features/pull_request_build.md +++ b/book/features/pull_request_build.md @@ -5,7 +5,7 @@ This section is useful for user type 3-5. ``` -When writing a TeachBook it is useful to automatically build and view these changes online. This exactly why we designed and build the [deploy-book-workflow](../external/deploy-book-workflow/README.md) tool, which also allows for multiple versions of your book to exist at any time with customizable URL's. However, it doesn't cover all use cases. Luckily, Read the Docs is a free tool that can easily be used for this purpose! +When writing a TeachBook it is useful to automatically build and view these changes online. This exactly why we designed and build the [deploy-book-workflow](../external/deploy-book-workflow/README.md) tool, which also allows for multiple versions of your book to exist at any time with customizable URL's. However, it doesn't cover all use cases. Luckily, Read the Docs is a free tool that can easily be used for this purpose. It also provides a very easy way to view differences between versions on each page! Pull Requests are a key tool for allowing anyone with a GitHub account to make a contribution to your work by forking your repository, adding commits, then sending them back to your repository via a Pull Request. Unfortunately you are not able to automatically build the book based on proposed changes in a pull request from a fork of your repository, as this requires the deploy-book-workflow in the fork to have GitHub Actions enabled 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 (e.g., with a hyperlink). This process can be made easier by using [Read the Docs](https://about.readthedocs.com/?ref=readthedocs.org), as it can automatically build a book based on changes proposed in a pull request, and includes a link to the book directly in the pull request page. From 3a2b64a8fa47305954051bf7195847681e9c02bf Mon Sep 17 00:00:00 2001 From: Robert Lanzafame Date: Mon, 17 Feb 2025 11:14:27 +0100 Subject: [PATCH 17/19] note about APA/local extensions --- book/features/pull_request_build.md | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/book/features/pull_request_build.md b/book/features/pull_request_build.md index 37aaec9..649b40c 100644 --- a/book/features/pull_request_build.md +++ b/book/features/pull_request_build.md @@ -11,7 +11,13 @@ Pull Requests are a key tool for allowing anyone with a GitHub account to make a Read the docs is not recommended for final versions of your book because of the advertisement in the free version. If you'd like to pay for it, it can replace the functionality of the [deploy-book-workflow](../external/deploy-book-workflow/README.md). -This workflow does not work if you have local sphinx extensions in your book (extensions in `book/_ext` like [](./apa.md)). +This tool works using Sphinx, which is the core engine for Jupyter Book; it is carried out using a Jupyter Book command to generate a Sphinx configuration file, for example: + +``` +jupyter-book config sphinx book/ +``` + +In theory this should work with the TeachBooks Python package `teachbooks` as well as local extensions (e.g., those in `book/_ext` like [](./apa.md)), but we have not checked this yet. If you are interested, try setting it up as a PR related to [this issue](https://github.com/TeachBooks/Read-the-Docs-example-book/issues/3). ```{tip} Once set up, this tool is only accessible via the Pull Request page for a repository in the 'Checks' part of the automated rule set box (illustrated below). This is different from our deploy-book-workflow, which is accessed From 205a30d059b1d33a2a60a219e5d243203ef34689 Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Mon, 17 Feb 2025 13:50:21 +0100 Subject: [PATCH 18/19] Remove something which doesn't work --- book/features/pull_request_build.md | 1 - 1 file changed, 1 deletion(-) diff --git a/book/features/pull_request_build.md b/book/features/pull_request_build.md index 649b40c..63f4ffd 100644 --- a/book/features/pull_request_build.md +++ b/book/features/pull_request_build.md @@ -62,7 +62,6 @@ build: python: install: - requirements: requirements.txt - - requirements: standard-imghdr sphinx: builder: html From 051decb130aefdbcea84aab9ec1ca1219fc49bc8 Mon Sep 17 00:00:00 2001 From: Robert Lanzafame Date: Tue, 18 Feb 2025 05:04:46 +0100 Subject: [PATCH 19/19] complete sentence. --- book/features/pull_request_build.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/book/features/pull_request_build.md b/book/features/pull_request_build.md index 63f4ffd..1ce4265 100644 --- a/book/features/pull_request_build.md +++ b/book/features/pull_request_build.md @@ -5,11 +5,11 @@ This section is useful for user type 3-5. ``` -When writing a TeachBook it is useful to automatically build and view these changes online. This exactly why we designed and build the [deploy-book-workflow](../external/deploy-book-workflow/README.md) tool, which also allows for multiple versions of your book to exist at any time with customizable URL's. However, it doesn't cover all use cases. Luckily, Read the Docs is a free tool that can easily be used for this purpose. It also provides a very easy way to view differences between versions on each page! +When writing a TeachBook it is useful to automatically build and view these changes online. This exactly why we designed and build the [deploy-book-workflow](../external/deploy-book-workflow/README.md) tool, which also allows for multiple versions of your book to exist at any time with customizable URL's. However, it doesn't cover all use cases. Luckily, **Read the Docs** is a free tool that can easily be used for this purpose. It also provides a very easy way to view differences between versions on each page! Pull Requests are a key tool for allowing anyone with a GitHub account to make a contribution to your work by forking your repository, adding commits, then sending them back to your repository via a Pull Request. Unfortunately you are not able to automatically build the book based on proposed changes in a pull request from a fork of your repository, as this requires the deploy-book-workflow in the fork to have GitHub Actions enabled 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 (e.g., with a hyperlink). This process can be made easier by using [Read the Docs](https://about.readthedocs.com/?ref=readthedocs.org), as it can automatically build a book based on changes proposed in a pull request, and includes a link to the book directly in the pull request page. -Read the docs is not recommended for final versions of your book because of the advertisement in the free version. If you'd like to pay for it, it can replace the functionality of the [deploy-book-workflow](../external/deploy-book-workflow/README.md). +Read the Docs is not recommended for final versions of your book because of the advertisement in the free version. If you'd like to pay for it, it can replace the functionality of the [deploy-book-workflow](../external/deploy-book-workflow/README.md). This tool works using Sphinx, which is the core engine for Jupyter Book; it is carried out using a Jupyter Book command to generate a Sphinx configuration file, for example: @@ -20,9 +20,9 @@ jupyter-book config sphinx book/ In theory this should work with the TeachBooks Python package `teachbooks` as well as local extensions (e.g., those in `book/_ext` like [](./apa.md)), but we have not checked this yet. If you are interested, try setting it up as a PR related to [this issue](https://github.com/TeachBooks/Read-the-Docs-example-book/issues/3). ```{tip} -Once set up, this tool is only accessible via the Pull Request page for a repository in the 'Checks' part of the automated rule set box (illustrated below). This is different from our deploy-book-workflow, which is accessed +Once set up, this tool is only accessible via the Pull Request page for a repository in the 'Checks' part of the automated rule set box (illustrated below under 'Usage'). This is different from our deploy-book-workflow, which is accessed under the Actions tab of a GitHub repository. -A Read the Docs account and admin privelages for the repository are only needed set this up; all visitors to the pull request page will be able to view the book, including the differencing feature. +A Read the Docs account and admin privelages for a repository are the only requirements needed set this up; all visitors to the pull request page will be able to view the book, including the differencing feature. ``` ## Usage