From ee2ee4321890231a9e6af942bb5653797349f772 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Tue, 17 Dec 2024 02:44:46 -0800 Subject: [PATCH 1/8] Use Read the Docs for pull request previews --- .github/workflows/rtd-pr-preview.yml | 22 ++++++++++++++++++++++ .readthedocs.yaml | 25 +++++++++++++++++++++++++ 2 files changed, 47 insertions(+) create mode 100644 .github/workflows/rtd-pr-preview.yml create mode 100644 .readthedocs.yaml diff --git a/.github/workflows/rtd-pr-preview.yml b/.github/workflows/rtd-pr-preview.yml new file mode 100644 index 00000000..b1be1f5f --- /dev/null +++ b/.github/workflows/rtd-pr-preview.yml @@ -0,0 +1,22 @@ +# .github/workflows/rtd-pr-preview.yml +name: readthedocs/actions +on: + pull_request_target: + types: + - opened + # Execute this action only on PRs that touch + # documentation files. + # paths: + # - "docs/**" + +permissions: + pull-requests: write + +jobs: + documentation-links: + runs-on: ubuntu-latest + steps: + - uses: readthedocs/actions/preview@v1 + with: + project-slug: "ploneapi" + single-version: "true" diff --git a/.readthedocs.yaml b/.readthedocs.yaml new file mode 100644 index 00000000..f32a2278 --- /dev/null +++ b/.readthedocs.yaml @@ -0,0 +1,25 @@ +# .readthedocs.yaml +# Read the Docs configuration file +# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details + +# Required +version: 2 + +# Set the OS, Python version and other tools you might need +build: + os: ubuntu-22.04 + tools: + python: "3.12" + 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 requirements.txt; + then + exit 183; + fi + - tox -e plone6docs From 1a02f35c0f26fa43f88414ca5a75d3468a9c9297 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Tue, 17 Dec 2024 03:01:55 -0800 Subject: [PATCH 2/8] Fiddle with commands to RTD --- .readthedocs.yaml | 2 ++ 1 file changed, 2 insertions(+) diff --git a/.readthedocs.yaml b/.readthedocs.yaml index f32a2278..c9cbccd4 100644 --- a/.readthedocs.yaml +++ b/.readthedocs.yaml @@ -22,4 +22,6 @@ build: then exit 183; fi + - pip install -r requirements.txt + - pip install -r requirements-docs.txt - tox -e plone6docs From c1e063bd5379d4d8eba71eb79b610a836e5c1f6e Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Tue, 17 Dec 2024 03:03:57 -0800 Subject: [PATCH 3/8] Drop to Python 3.11 because plone.api does not yet officially support 3.12 --- .readthedocs.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.readthedocs.yaml b/.readthedocs.yaml index c9cbccd4..f985ae36 100644 --- a/.readthedocs.yaml +++ b/.readthedocs.yaml @@ -9,7 +9,7 @@ version: 2 build: os: ubuntu-22.04 tools: - python: "3.12" + 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, From 975c810969e92a3478144c7521632e7f3c838f33 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Tue, 17 Dec 2024 03:18:02 -0800 Subject: [PATCH 4/8] Specify where to put built files on RTD --- .readthedocs.yaml | 4 ++-- tox.ini | 17 +++++++++++++++++ 2 files changed, 19 insertions(+), 2 deletions(-) diff --git a/.readthedocs.yaml b/.readthedocs.yaml index f985ae36..38273c59 100644 --- a/.readthedocs.yaml +++ b/.readthedocs.yaml @@ -23,5 +23,5 @@ build: exit 183; fi - pip install -r requirements.txt - - pip install -r requirements-docs.txt - - tox -e plone6docs +# - pip install -r requirements-docs.txt + - tox -e rtd-preview diff --git a/tox.ini b/tox.ini index cc85d042..07c89024 100644 --- a/tox.ini +++ b/tox.ini @@ -271,6 +271,23 @@ commands = mkdir -p {toxinidir}/_build/plone6docs sphinx-build -b html -d _build/plone6docs/doctrees docs _build/plone6docs/html +[testenv:rtd-preview] +# New docs with sphinx-book-theme +# See [testenv:docs] for classic documentation +basepython = python3.11 +skip_install = False +package = editable +allowlist_externals = + mkdir +extras = + tests +deps = + -r requirements-docs.txt +commands = + python -VV + mkdir -p {toxinidir}/${READTHEDOCS_OUTPUT} + sphinx-build -b html -d ${READTHEDOCS_OUTPUT}/doctrees/ docs ${READTHEDOCS_OUTPUT}/html/ + [testenv:docs] basepython = python3.9 skip_install = False From dce02cf0f697d71f2edad6b179bd209bb384eaaa Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Tue, 17 Dec 2024 03:21:35 -0800 Subject: [PATCH 5/8] Fiddle with tox syntax --- tox.ini | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/tox.ini b/tox.ini index 07c89024..3953cc06 100644 --- a/tox.ini +++ b/tox.ini @@ -285,8 +285,8 @@ deps = -r requirements-docs.txt commands = python -VV - mkdir -p {toxinidir}/${READTHEDOCS_OUTPUT} - sphinx-build -b html -d ${READTHEDOCS_OUTPUT}/doctrees/ docs ${READTHEDOCS_OUTPUT}/html/ + mkdir -p {toxinidir}/$READTHEDOCS_OUTPUT + sphinx-build -b html -d $READTHEDOCS_OUTPUT/doctrees/ docs $READTHEDOCS_OUTPUT/html/ [testenv:docs] basepython = python3.9 From 6d88ea717a5a071c5ced7353dd75bf50be3e705b Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Tue, 17 Dec 2024 03:32:11 -0800 Subject: [PATCH 6/8] Fiddle with tox syntax attempt 2 --- tox.ini | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/tox.ini b/tox.ini index 3953cc06..b8c64bd9 100644 --- a/tox.ini +++ b/tox.ini @@ -285,8 +285,7 @@ deps = -r requirements-docs.txt commands = python -VV - mkdir -p {toxinidir}/$READTHEDOCS_OUTPUT - sphinx-build -b html -d $READTHEDOCS_OUTPUT/doctrees/ docs $READTHEDOCS_OUTPUT/html/ + sphinx-build -b html -d "{env:READTHEDOCS_OUTPUT}"/doctrees/ docs "{env:READTHEDOCS_OUTPUT}"/html/" [testenv:docs] basepython = python3.9 From 949a16a7180dadca7fb641ba375526e162b184e6 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Tue, 17 Dec 2024 03:35:13 -0800 Subject: [PATCH 7/8] Fiddle with tox syntax attempt 3 --- tox.ini | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tox.ini b/tox.ini index b8c64bd9..eb6b27ae 100644 --- a/tox.ini +++ b/tox.ini @@ -285,7 +285,7 @@ deps = -r requirements-docs.txt commands = python -VV - sphinx-build -b html -d "{env:READTHEDOCS_OUTPUT}"/doctrees/ docs "{env:READTHEDOCS_OUTPUT}"/html/" + sphinx-build -b html -d "{env:READTHEDOCS_OUTPUT}"/doctrees/ docs "{env:READTHEDOCS_OUTPUT}"/html/ [testenv:docs] basepython = python3.9 From b5e510fe5124c3a99bb1f952a7e9d3413c5bd085 Mon Sep 17 00:00:00 2001 From: David Glick Date: Tue, 17 Dec 2024 16:39:34 -0800 Subject: [PATCH 8/8] news and manifest --- MANIFEST.in | 1 + news/545.documentation | 1 + 2 files changed, 2 insertions(+) create mode 100644 news/545.documentation diff --git a/MANIFEST.in b/MANIFEST.in index 162a5ec9..c89b5bdb 100644 --- a/MANIFEST.in +++ b/MANIFEST.in @@ -14,6 +14,7 @@ include pyproject.toml recursive-exclude news * exclude news recursive-exclude .vscode * +exclude .readthedocs.yaml # added by check-manifest recursive-include src *.py diff --git a/news/545.documentation b/news/545.documentation new file mode 100644 index 00000000..ac078ab0 --- /dev/null +++ b/news/545.documentation @@ -0,0 +1 @@ +Preview docs on Read the Docs instead of Netlify. @stevepiercy