From eb9d30f15ea87f52ad9d3bc8e34aac4a000ffde1 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Sun, 30 Jun 2024 19:52:40 -0700 Subject: [PATCH 01/21] Add pull request preview on Read the Docs Note: Requires enabling this feature on RTD by a Maintainer --- .readthedocs.yml | 14 ++++++++++++++ CHANGES.rst | 1 + docs/Makefile | 5 ++++- 3 files changed, 19 insertions(+), 1 deletion(-) diff --git a/.readthedocs.yml b/.readthedocs.yml index 572db76f..0ae8614c 100644 --- a/.readthedocs.yml +++ b/.readthedocs.yml @@ -16,6 +16,20 @@ build: os: ubuntu-22.04 tools: python: "3.11" + commands: + # Cancel building pull requests when there aren't changes in the docs directory or YAML file. + # You can add any other files or directories that you'd like here as well, + # like your docs requirements file, or other files that will change your docs build. + # + # If there are no changes (git diff exits with 0) we force the command to return with 183. + # This is a special exit code on Read the Docs that will cancel the build immediately. + - | + if [ "$READTHEDOCS_VERSION_TYPE" = "external" ] && git diff --quiet origin/main -- docs/ .readthedocs.yaml requirements_docs.txt; + then + exit 183; + fi + - cd docs + - make rtd-pr-preview python: install: diff --git a/CHANGES.rst b/CHANGES.rst index e1c5d9f1..8145656f 100644 --- a/CHANGES.rst +++ b/CHANGES.rst @@ -61,6 +61,7 @@ New features: - Test compatibility with Python 3.12 - Add function ``icalendar.use_pytz()``. +- Add pull request preview on Read the Docs. Bug fixes: diff --git a/docs/Makefile b/docs/Makefile index 7310e33b..e76d46ad 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -15,7 +15,7 @@ ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . # the i18n builder cannot share the environment and doctrees with the others I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . -.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext +.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext rtd-pr-preview help: @echo "Please use \`make ' where is one of" @@ -159,3 +159,6 @@ doctest: $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest @echo "Testing of doctests in the sources finished, look at the " \ "results in $(BUILDDIR)/doctest/output.txt." + +rtd-pr-preview: ## Build pull request preview on Read the Docs + $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) ${READTHEDOCS_OUTPUT}/html/ From 9b601824ec2e84a425f00747e3360693a4561213 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Mon, 1 Jul 2024 18:21:07 -0700 Subject: [PATCH 02/21] Include additional files and paths to include in documentation builds --- .readthedocs.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.readthedocs.yml b/.readthedocs.yml index 0ae8614c..d8212123 100644 --- a/.readthedocs.yml +++ b/.readthedocs.yml @@ -24,7 +24,7 @@ build: # If there are no changes (git diff exits with 0) we force the command to return with 183. # This is a special exit code on Read the Docs that will cancel the build immediately. - | - if [ "$READTHEDOCS_VERSION_TYPE" = "external" ] && git diff --quiet origin/main -- docs/ .readthedocs.yaml requirements_docs.txt; + if [ "$READTHEDOCS_VERSION_TYPE" = "external" ] && git diff --quiet origin/main -- docs/ src/icalender/*.py CHANGES.rst CONTRIBUTING.rst LICENSE.rst README.rst .readthedocs.yaml requirements_docs.txt; then exit 183; fi From 29bba58da461c3479d8559d4f91301f01b8c9b51 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Mon, 1 Jul 2024 18:23:50 -0700 Subject: [PATCH 03/21] Debug RTD build --- .readthedocs.yml | 1 + 1 file changed, 1 insertion(+) diff --git a/.readthedocs.yml b/.readthedocs.yml index d8212123..c3ec41b0 100644 --- a/.readthedocs.yml +++ b/.readthedocs.yml @@ -29,6 +29,7 @@ build: exit 183; fi - cd docs + - cat Makefile - make rtd-pr-preview python: From 71f9d48ee1db7e6ee65f3f20312f88d838c86c62 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Mon, 1 Jul 2024 18:26:14 -0700 Subject: [PATCH 04/21] Debug RTD build --- .readthedocs.yml | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/.readthedocs.yml b/.readthedocs.yml index c3ec41b0..c45f2ef5 100644 --- a/.readthedocs.yml +++ b/.readthedocs.yml @@ -29,7 +29,8 @@ build: exit 183; fi - cd docs - - cat Makefile + - pwd + - ls -al - make rtd-pr-preview python: From 3e28195c09501ea71d8e25cd86e39f8301f91987 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Mon, 1 Jul 2024 18:27:47 -0700 Subject: [PATCH 05/21] Debug RTD build --- .readthedocs.yml | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) diff --git a/.readthedocs.yml b/.readthedocs.yml index c45f2ef5..758a49e3 100644 --- a/.readthedocs.yml +++ b/.readthedocs.yml @@ -28,10 +28,7 @@ build: then exit 183; fi - - cd docs - - pwd - - ls -al - - make rtd-pr-preview + - cd docs && pwd && ls -al && make rtd-pr-preview python: install: From d260cfeca62dd7bc2b6288f6f689fc3c0a93680c Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Mon, 1 Jul 2024 18:31:21 -0700 Subject: [PATCH 06/21] Debug RTD build --- docs/Makefile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/Makefile b/docs/Makefile index 5b545fc8..56e28fe2 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -168,4 +168,4 @@ livehtml: -b html . "$(BUILDDIR)/html" $(SPHINXOPTS) $(O) rtd-pr-preview: ## Build pull request preview on Read the Docs - $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) ${READTHEDOCS_OUTPUT}/html/ + ${READTHEDOCS_VIRTUALENV_PATH}$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) ${READTHEDOCS_OUTPUT}/html/ From bda2ca56992ee973c14b5270c643cb4eb5fd0fb6 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Mon, 1 Jul 2024 18:32:02 -0700 Subject: [PATCH 07/21] Debug RTD build --- docs/Makefile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/Makefile b/docs/Makefile index 56e28fe2..00bf29d7 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -168,4 +168,4 @@ livehtml: -b html . "$(BUILDDIR)/html" $(SPHINXOPTS) $(O) rtd-pr-preview: ## Build pull request preview on Read the Docs - ${READTHEDOCS_VIRTUALENV_PATH}$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) ${READTHEDOCS_OUTPUT}/html/ + ${READTHEDOCS_VIRTUALENV_PATH}/$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) ${READTHEDOCS_OUTPUT}/html/ From 8d6110c057a99d72c49197585a96e6446e53e076 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Mon, 1 Jul 2024 18:32:55 -0700 Subject: [PATCH 08/21] Debug RTD build --- docs/Makefile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/Makefile b/docs/Makefile index 00bf29d7..8a57fc6f 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -168,4 +168,4 @@ livehtml: -b html . "$(BUILDDIR)/html" $(SPHINXOPTS) $(O) rtd-pr-preview: ## Build pull request preview on Read the Docs - ${READTHEDOCS_VIRTUALENV_PATH}/$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) ${READTHEDOCS_OUTPUT}/html/ + ${READTHEDOCS_VIRTUALENV_PATH}/bin/$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) ${READTHEDOCS_OUTPUT}/html/ From 86d2b751536ffc3c0e9cedd274af5771db83a059 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Mon, 1 Jul 2024 18:34:19 -0700 Subject: [PATCH 09/21] Debug RTD build --- .readthedocs.yml | 2 ++ 1 file changed, 2 insertions(+) diff --git a/.readthedocs.yml b/.readthedocs.yml index 758a49e3..99dd3f2f 100644 --- a/.readthedocs.yml +++ b/.readthedocs.yml @@ -28,6 +28,8 @@ build: then exit 183; fi + - echo ${READTHEDOCS_VIRTUALENV_PATH} + - ls -al ${READTHEDOCS_VIRTUALENV_PATH} - cd docs && pwd && ls -al && make rtd-pr-preview python: From 531fd14f91816fedc78fbbdf74d38686b78a17de Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Mon, 1 Jul 2024 18:38:53 -0700 Subject: [PATCH 10/21] Forego Makefile command --- .readthedocs.yml | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/.readthedocs.yml b/.readthedocs.yml index 99dd3f2f..c6daf88c 100644 --- a/.readthedocs.yml +++ b/.readthedocs.yml @@ -28,9 +28,7 @@ build: then exit 183; fi - - echo ${READTHEDOCS_VIRTUALENV_PATH} - - ls -al ${READTHEDOCS_VIRTUALENV_PATH} - - cd docs && pwd && ls -al && make rtd-pr-preview + - sphinx-build -b html -d ${READTHEDOCS_OUTPUT}/doctrees ${READTHEDOCS_OUTPUT}/html/ python: install: From 82c5ca6d0a9dc046c5ab42c068bb99ecceb32750 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Mon, 1 Jul 2024 18:42:39 -0700 Subject: [PATCH 11/21] Try again --- .readthedocs.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.readthedocs.yml b/.readthedocs.yml index c6daf88c..57833252 100644 --- a/.readthedocs.yml +++ b/.readthedocs.yml @@ -28,7 +28,7 @@ build: then exit 183; fi - - sphinx-build -b html -d ${READTHEDOCS_OUTPUT}/doctrees ${READTHEDOCS_OUTPUT}/html/ + - cd docs && "$(realpath bin/sphinx-build)" -b html -d ${READTHEDOCS_OUTPUT}/doctrees ${READTHEDOCS_OUTPUT}/html/ python: install: From 38245cc944b9e2dab788f3e48ca49e0277a83af2 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Mon, 1 Jul 2024 18:44:09 -0700 Subject: [PATCH 12/21] Try again --- .readthedocs.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.readthedocs.yml b/.readthedocs.yml index 57833252..03ccf0c3 100644 --- a/.readthedocs.yml +++ b/.readthedocs.yml @@ -28,7 +28,7 @@ build: then exit 183; fi - - cd docs && "$(realpath bin/sphinx-build)" -b html -d ${READTHEDOCS_OUTPUT}/doctrees ${READTHEDOCS_OUTPUT}/html/ + - cd docs && ${READTHEDOCS_VIRTUALENV_PATH}/bin/sphinx-build -b html -d ${READTHEDOCS_OUTPUT}/doctrees ${READTHEDOCS_OUTPUT}/html/ python: install: From 78a495ae705c7fe006493d29e8bdb0ed7e00b1a2 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Mon, 1 Jul 2024 18:44:46 -0700 Subject: [PATCH 13/21] Try again --- .readthedocs.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.readthedocs.yml b/.readthedocs.yml index 03ccf0c3..991307e1 100644 --- a/.readthedocs.yml +++ b/.readthedocs.yml @@ -28,7 +28,7 @@ build: then exit 183; fi - - cd docs && ${READTHEDOCS_VIRTUALENV_PATH}/bin/sphinx-build -b html -d ${READTHEDOCS_OUTPUT}/doctrees ${READTHEDOCS_OUTPUT}/html/ + - cd docs && ${READTHEDOCS_VIRTUALENV_PATH}/sphinx-build -b html -d ${READTHEDOCS_OUTPUT}/doctrees ${READTHEDOCS_OUTPUT}/html/ python: install: From ab7124d60e9f9af558b83ce16fd38a6cad2bace1 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Mon, 1 Jul 2024 18:47:05 -0700 Subject: [PATCH 14/21] Try again --- .readthedocs.yml | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/.readthedocs.yml b/.readthedocs.yml index 991307e1..1ce2856a 100644 --- a/.readthedocs.yml +++ b/.readthedocs.yml @@ -28,7 +28,8 @@ build: then exit 183; fi - - cd docs && ${READTHEDOCS_VIRTUALENV_PATH}/sphinx-build -b html -d ${READTHEDOCS_OUTPUT}/doctrees ${READTHEDOCS_OUTPUT}/html/ + - cd docs && cat Makefile + - make rtd-pr-preview python: install: From 1cfff949623c661e121b2072655c7df7457dc4be Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Mon, 1 Jul 2024 18:47:47 -0700 Subject: [PATCH 15/21] Try again --- .readthedocs.yml | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/.readthedocs.yml b/.readthedocs.yml index 1ce2856a..97a64363 100644 --- a/.readthedocs.yml +++ b/.readthedocs.yml @@ -28,8 +28,7 @@ build: then exit 183; fi - - cd docs && cat Makefile - - make rtd-pr-preview + - cd docs && cat Makefile && make rtd-pr-preview python: install: From ff3f762387ebe1f83cde48e6361f72c47fc2c478 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Mon, 1 Jul 2024 18:49:10 -0700 Subject: [PATCH 16/21] debug --- .readthedocs.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.readthedocs.yml b/.readthedocs.yml index 97a64363..25fd3e46 100644 --- a/.readthedocs.yml +++ b/.readthedocs.yml @@ -28,7 +28,7 @@ build: then exit 183; fi - - cd docs && cat Makefile && make rtd-pr-preview + - cd docs && cat Makefile && which sphinx-build && ls -al ${READTHEDOCS_VIRTUALENV_PATH} # make rtd-pr-preview python: install: From 0c76e061cf1f047b5fd82ac96c869c6e2ab1c02f Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Mon, 1 Jul 2024 18:50:07 -0700 Subject: [PATCH 17/21] debug --- .readthedocs.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.readthedocs.yml b/.readthedocs.yml index 25fd3e46..f6fda287 100644 --- a/.readthedocs.yml +++ b/.readthedocs.yml @@ -28,7 +28,7 @@ build: then exit 183; fi - - cd docs && cat Makefile && which sphinx-build && ls -al ${READTHEDOCS_VIRTUALENV_PATH} # make rtd-pr-preview + - cd docs && cat Makefile && which sphinx-build && ls -al $READTHEDOCS_VIRTUALENV_PATH # make rtd-pr-preview python: install: From c79e9a113fef73de0c9b81088930bb65de9a0900 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Mon, 1 Jul 2024 18:51:23 -0700 Subject: [PATCH 18/21] debug --- .readthedocs.yml | 7 +------ 1 file changed, 1 insertion(+), 6 deletions(-) diff --git a/.readthedocs.yml b/.readthedocs.yml index f6fda287..a9c60b6e 100644 --- a/.readthedocs.yml +++ b/.readthedocs.yml @@ -28,10 +28,5 @@ build: then exit 183; fi + - pip install -r requirements_docs.txt - cd docs && cat Makefile && which sphinx-build && ls -al $READTHEDOCS_VIRTUALENV_PATH # make rtd-pr-preview - -python: - install: - - requirements: requirements_docs.txt - - method: pip - path: . From 1769a7a74646e5c2c2a8b23d16079f403f592a0e Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Mon, 1 Jul 2024 18:53:28 -0700 Subject: [PATCH 19/21] debug --- .readthedocs.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.readthedocs.yml b/.readthedocs.yml index a9c60b6e..03ad3951 100644 --- a/.readthedocs.yml +++ b/.readthedocs.yml @@ -29,4 +29,4 @@ build: exit 183; fi - pip install -r requirements_docs.txt - - cd docs && cat Makefile && which sphinx-build && ls -al $READTHEDOCS_VIRTUALENV_PATH # make rtd-pr-preview + - cd docs && make rtd-pr-preview # make rtd-pr-preview From dda769955f50fc72bbe00345cf7dbdf644b98504 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Mon, 1 Jul 2024 18:54:40 -0700 Subject: [PATCH 20/21] debug --- docs/Makefile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/Makefile b/docs/Makefile index 8a57fc6f..5b545fc8 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -168,4 +168,4 @@ livehtml: -b html . "$(BUILDDIR)/html" $(SPHINXOPTS) $(O) rtd-pr-preview: ## Build pull request preview on Read the Docs - ${READTHEDOCS_VIRTUALENV_PATH}/bin/$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) ${READTHEDOCS_OUTPUT}/html/ + $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) ${READTHEDOCS_OUTPUT}/html/ From 050238e1c3827689ae321484b02ef6ffb25ccaab Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Mon, 1 Jul 2024 18:59:17 -0700 Subject: [PATCH 21/21] Remove useless comment --- .readthedocs.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.readthedocs.yml b/.readthedocs.yml index 03ad3951..a0b0bec4 100644 --- a/.readthedocs.yml +++ b/.readthedocs.yml @@ -29,4 +29,4 @@ build: exit 183; fi - pip install -r requirements_docs.txt - - cd docs && make rtd-pr-preview # make rtd-pr-preview + - cd docs && make rtd-pr-preview