From e1f700ad5fc260cc0dc5b2ac93519599cc61d92a Mon Sep 17 00:00:00 2001 From: Robert Lanzafame Date: Mon, 17 Feb 2025 10:17:57 +0100 Subject: [PATCH] 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: