Replace Netlify with Read the Docs build previews #103843

hugovk · 2023-04-25T17:08:30Z

Let's use Read the Docs for documentation previews instead of Netlify.

Benefits:

Most important: we can add many admins to the RtD project, compared to a single-person for Netlify which causes bottlenecks
We're using RtD for PEPs and devguide previews and it's working well
The RtD team have been very helpful, and it's nice to keep things in the Python family
We can use the https://github.com/readthedocs/actions/tree/main/preview action we're using on the other repos
As a longer term plan, I'd also like to use RtD for hosting the HTML docs rather than the build server, but that's for another discussion.

TODO

Set up an RtD project, needs someone with sufficient permissions to set up the webhooks. ~~Needs to be done before merge.~~
Disable the Netlify connection to this repo. Task for Ee, can possibly be done later after merge?
Merge

.github/workflows/documentation-links.yml

CAM-Gerlach

Thanks! A couple comments. Also, shouldn't this be merged before turning on the RTD project so the config is correct? Or at least as soon as possible?

.github/workflows/documentation-links.yml

Doc/conf.py

.github/workflows/documentation-links.yml

sobolevn · 2023-04-25T20:00:35Z

Nice idea!

.github/workflows/documentation-links.yml

hugovk · 2023-04-25T20:39:12Z

Also, shouldn't this be merged before turning on the RTD project so the config is correct? Or at least as soon as possible?

The docs still build without the config, but it's slower because it builds more than just html, and also installs the other default stuff we don't need when not overriding the build commands. Iirc about 5 mins to 2 mins.

But yes, we can also merge first.

willingc · 2023-04-26T17:07:38Z

Great idea. Thanks @hugovk

Co-authored-by: Oleg Iarygin <dralife@yandex.ru> Co-authored-by: C.A.M. Gerlach <CAM.Gerlach@Gerlach.CAM>

ezio-melotti · 2023-04-26T20:24:21Z

.github/workflows/documentation-links.yml

@@ -0,0 +1,24 @@
+name: Read the Docs PR preview


Somewhat unrelated to this specific PR, but I think it would be useful to add a comment (or a docstring-like description if there is a field for it) to document what the workflow is for. If it's not possible to do it here, we could document the workflows either in a README in the dir or somewhere in the devguide.

Good suggestion @ezio-melotti

CAM-Gerlach

LGTM, thanks @hugovk !

hugovk · 2023-04-30T04:57:43Z

@Mariatta has created an RtD project https://readthedocs.org/projects/cpython-previews/ and added me and @ambv as maintainers. Anyone else to add?

The first build passed!

On https://readthedocs.org/dashboard/cpython-previews/edit/ I added a "Description" and "Project homepage":

Details

On https://readthedocs.org/dashboard/cpython-previews/advanced/ I checked "Disable Analytics", "Show version warning" and "Build pull requests for this project":

Details

Everything else is the default.

Let's merge this PR with the config, it'll make the build times quicker.

arhadthedev · 2023-04-30T05:09:55Z

Disable the Netlify connection to this repo. Task for Ee, can possibly be done later after merge?

@ewdurbin

hugovk · 2023-04-30T05:17:06Z

Pre-merge build

Build took 430 seconds with Python 3.7, built html and htmlzip:

Details

https://readthedocs.org/projects/cpython-previews/builds/20337268/

Post-merge build with config file

Build took 247 seconds with Python 3.11, built html only:

Details

https://readthedocs.org/projects/cpython-previews/builds/20337291/

PR deploy preview

Here's #103457 showing the preview banner at https://cpython-previews--103457.org.readthedocs.build/en/103457/

Details

hugovk · 2023-04-30T06:10:19Z

@ewdurbin Please could you disable Netlify via https://app.netlify.com/sites/python-cpython-preview/settings/deploys:

ewdurbin · 2023-04-30T18:16:49Z

Done.

* main: (26 commits) pythongh-104028: Reduce object creation while calling callback function from gc (pythongh-104030) pythongh-104036: Fix direct invocation of test_typing (python#104037) pythongh-102213: Optimize the performance of `__getattr__` (pythonGH-103761) pythongh-103895: Improve how invalid `Exception.__notes__` are displayed (python#103897) Adjust expression from `==` to `!=` in alignment with the meaning of the paragraph. (pythonGH-104021) pythongh-88496: Fix IDLE test hang on macOS (python#104025) Improve int test coverage (python#104024) pythongh-88773: Added teleport method to Turtle library (python#103974) pythongh-104015: Fix direct invocation of `test_dataclasses` (python#104017) pythongh-104012: Ensure test_calendar.CalendarTestCase.test_deprecation_warning consistently passes (python#104014) pythongh-103977: compile re expressions in platform.py only if required (python#103981) pythongh-98003: Inline call frames for CALL_FUNCTION_EX (pythonGH-98004) Replace Netlify with Read the Docs build previews (python#103843) Update name in acknowledgements and add mailmap (python#103696) pythongh-82054: allow test runner to split test_asyncio to execute in parallel by sharding. (python#103927) Remove non-existing tools from Sundry skiplist (python#103991) pythongh-103793: Defer formatting task name (python#103767) pythongh-87092: change assembler to use instruction sequence instead of CFG (python#103933) pythongh-103636: issue warning for deprecated calendar constants (python#103833) Various small fixes to dis docs (python#103923) ...

humitos · 2023-05-01T20:33:09Z

netlify.toml

-    publish = "build/html"
-    # Do not trigger netlify builds if docs were not changed.
-    # Changed files should be in sync with `.github/workflows/doc.yml`
-    ignore = "git diff --quiet $CACHED_COMMIT_REF $COMMIT_REF . ../netlify.toml"


You can keep something like this on RTD (cancel the build if there is no changes at Doc/ directory, for example) by running a test command that exits with code 183. Take a look at https://docs.readthedocs.io/en/latest/builds.html#cancelling-builds for more information.

We have something like this at Read the Docs itself in our config file: https://github.com/readthedocs/readthedocs.org/blob/main/.readthedocs.yml#L28

Attempted in #104100.

miss-islington · 2023-05-02T04:54:06Z

Thanks @hugovk for the PR 🌮🎉.. I'm working now to backport this PR to: 3.11.
🐍🍒⛏🤖

miss-islington · 2023-05-02T04:54:07Z

Sorry, @hugovk, I could not cleanly backport this to 3.11 due to a conflict.
Please backport using cherry_picker on command line.
cherry_picker accb417c338630ac6e836a5c811a89d54a3cd1d3 3.11

Co-authored-by: Oleg Iarygin <dralife@yandex.ru> Co-authored-by: C.A.M. Gerlach <CAM.Gerlach@Gerlach.CAM> (cherry picked from commit accb417)

bedevere-bot · 2023-05-02T04:59:25Z

GH-104083 is a backport of this pull request to the 3.11 branch.

…104083) Co-authored-by: Oleg Iarygin <dralife@yandex.ru> Co-authored-by: C.A.M. Gerlach <CAM.Gerlach@Gerlach.CAM>

Replace Netlify with Read the Docs build previews

a4f030b

hugovk added docs Documentation in the Doc dir skip issue skip news labels Apr 25, 2023

arhadthedev reviewed Apr 25, 2023

View reviewed changes

.github/workflows/documentation-links.yml Outdated Show resolved Hide resolved

CAM-Gerlach reviewed Apr 25, 2023

View reviewed changes

.github/workflows/documentation-links.yml Outdated Show resolved Hide resolved

Doc/conf.py Outdated Show resolved Hide resolved

sobolevn reviewed Apr 25, 2023

View reviewed changes

.github/workflows/documentation-links.yml Show resolved Hide resolved

CAM-Gerlach reviewed Apr 25, 2023

View reviewed changes

.github/workflows/documentation-links.yml Show resolved Hide resolved

hugovk and others added 4 commits April 26, 2023 20:09

Merge remote-tracking branch 'upstream/main' into rtd-docs-preview

855290c

Apply suggestions from code review

8008308

Co-authored-by: Oleg Iarygin <dralife@yandex.ru> Co-authored-by: C.A.M. Gerlach <CAM.Gerlach@Gerlach.CAM>

Cancel in-progress workflows

c421383

Set is_deployment_preview flag for PR builds instead of all RtD builds

2d04997

hugovk marked this pull request as ready for review April 26, 2023 20:08

hugovk requested a review from ezio-melotti as a code owner April 26, 2023 20:08

ezio-melotti reviewed Apr 26, 2023

View reviewed changes

Add a comment describing the purpose of the workflow

8d7a571

CAM-Gerlach approved these changes Apr 27, 2023

View reviewed changes

bedevere-bot added the awaiting merge label Apr 27, 2023

CAM-Gerlach added the DO-NOT-MERGE label Apr 27, 2023

hugovk mentioned this pull request Apr 29, 2023

Netlify preview builds silently fail with Deploy Preview canceled #103604

Closed

arhadthedev mentioned this pull request Apr 29, 2023

gh-103604: Fix incorrect paths in netlify.toml #103605

Closed

AA-Turner approved these changes Apr 29, 2023

View reviewed changes

hugovk removed the DO-NOT-MERGE label Apr 30, 2023

hugovk merged commit accb417 into python:main Apr 30, 2023

bedevere-bot removed the awaiting merge label Apr 30, 2023

humitos reviewed May 1, 2023

View reviewed changes

hugovk mentioned this pull request May 2, 2023

Docs: Fix build preview banner #104082

Closed

hugovk added the needs backport to 3.11 only security fixes label May 2, 2023

miss-islington assigned hugovk May 2, 2023

bedevere-bot removed the needs backport to 3.11 only security fixes label May 2, 2023

hugovk added a commit that referenced this pull request May 2, 2023

[3.11] Replace Netlify with Read the Docs build previews (#103843) (#…

b07bae6

…104083) Co-authored-by: Oleg Iarygin <dralife@yandex.ru> Co-authored-by: C.A.M. Gerlach <CAM.Gerlach@Gerlach.CAM>

hugovk mentioned this pull request May 2, 2023

RtD docs previews: Cancel building PRs if no changes in Doc dir #104100

Merged

jiridanek mentioned this pull request Jan 2, 2024

Possible heap-use-after-free in ctypes in Python 3.12 #113576

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Replace Netlify with Read the Docs build previews #103843

Replace Netlify with Read the Docs build previews #103843

hugovk commented Apr 25, 2023 •

edited

Loading

CAM-Gerlach left a comment

sobolevn commented Apr 25, 2023

hugovk commented Apr 25, 2023

willingc commented Apr 26, 2023

ezio-melotti Apr 26, 2023

willingc Apr 26, 2023

hugovk Apr 27, 2023

CAM-Gerlach left a comment

hugovk commented Apr 30, 2023 •

edited

Loading

arhadthedev commented Apr 30, 2023

hugovk commented Apr 30, 2023

hugovk commented Apr 30, 2023

ewdurbin commented Apr 30, 2023

humitos May 1, 2023

hugovk May 3, 2023

miss-islington commented May 2, 2023

miss-islington commented May 2, 2023

bedevere-bot commented May 2, 2023

Replace Netlify with Read the Docs build previews #103843

Replace Netlify with Read the Docs build previews #103843

Conversation

hugovk commented Apr 25, 2023 • edited Loading

TODO

CAM-Gerlach left a comment

Choose a reason for hiding this comment

sobolevn commented Apr 25, 2023

hugovk commented Apr 25, 2023

willingc commented Apr 26, 2023

ezio-melotti Apr 26, 2023

Choose a reason for hiding this comment

willingc Apr 26, 2023

Choose a reason for hiding this comment

hugovk Apr 27, 2023

Choose a reason for hiding this comment

CAM-Gerlach left a comment

Choose a reason for hiding this comment

hugovk commented Apr 30, 2023 • edited Loading

arhadthedev commented Apr 30, 2023

hugovk commented Apr 30, 2023

Pre-merge build

Post-merge build with config file

PR deploy preview

hugovk commented Apr 30, 2023

ewdurbin commented Apr 30, 2023

humitos May 1, 2023

Choose a reason for hiding this comment

hugovk May 3, 2023

Choose a reason for hiding this comment

miss-islington commented May 2, 2023

miss-islington commented May 2, 2023

bedevere-bot commented May 2, 2023

hugovk commented Apr 25, 2023 •

edited

Loading

hugovk commented Apr 30, 2023 •

edited

Loading