René's URL Explorer Experiment

{"@context":"https://schema.org","@type":"DiscussionForumPosting","headline":"Pull request preview builds for online docs","articleBody":"[Read the Docs](https://about.readthedocs.com/) supports [pull request builds](https://docs.readthedocs.io/en/stable/pull-requests.html), where pull requests trigger preview builds that are published to a different domain and marked with a warning banner to prevent confusion, and where the build status is reported as one of the CI checks for the PR.\r\n\r\nI recommend enabling this for GitPython. Unlike some CI checks that are configured in GitHub Actions workflow files, my understanding is that Read the Docs pull request builds, including their status reporting as CI checks, do not use GitHub Actions. Instead, pull request builds are triggered via webhook (as are other Read the Docs builds), and the check status is reported to GitHub by authenticating with OAuth and posting it with (I think) the GitHub API.\r\n\r\nFor this reason, I don't believe I can propose the necessary changes by pull request. Instead, if you choose to enable pull request builds, [you can do so by following these official instructions](https://docs.readthedocs.io/en/stable/guides/pull-requests.html).\r\n\r\nThis should make it easier to verify the correctness of documentation changes in pull requests, as well as make it easier for contributors (including me) to become aware of, investigate, and attempt to improve problems in Read the Docs builds.\r\n\r\nMy immediate motivation for recommending this change is the hope that it would enable me to submit and test a fix for #1840. However, even if it turns out that the effect of changes to `.readthedocs.yaml` are not fully previewed in pull request builds--I think they are but I am not sure--it seems to me that this would be a worthwhile addition to the project's CI checks.\r\n\r\nCurrently the `pythonpackage.yml` workflow does test if a *local* documentation build is able to succeed, but this does not test if a remote (Read the Docs) build succeeds, and more importantly it does not produce a hosted preview of the built documentation that can be easily inspected.","author":{"url":"https://github.com/EliahKagan","@type":"Person","name":"EliahKagan"},"datePublished":"2024-02-23T19:01:25.000Z","interactionStatistic":{"@type":"InteractionCounter","interactionType":"https://schema.org/CommentAction","userInteractionCount":7},"url":"https://github.com/1842/GitPython/issues/1842"}