bpo-37860: re-add netlify.toml to set up deploy previews for docs

[epicfaace]

Fixes#82041 by setting up Netlify to set up deploy previews for docs.

This PR re-does #15288. Reverts #30272 (where we had originally removed netlify.toml due to build limits). As per #82041 (comment), the build limits are now large enough that they should be fine to use for cpython.

[epicfaace]

Do we need a NEWS label for this? I was thinking we could skip news?

[hugovk]

Thanks for this!

I added the skip news label.

Please could you do a deploy to a demo site first to check the command still works three years later?

For example, Ubuntu Focal is now the default image, and the default Python is 3.8 (not 2.7) so may be able to skip Doc/runtime.txt altogether.

https://github.com/netlify/build-image/blob/focal/included_software.md

[epicfaace]

@hugovk made some small fixes, it now deploys correctly. My branch is deployed at: https://steady-heliotrope-731cac.netlify.app/

[hugovk]

Good work! Out of interest, how long does a single build/deploy take?

[epicfaace]

It took 4m16s.

[hugovk]

Thanks, so with 25,000 minutes per month, 4-5 minutes per build gives us 5,000-6,250 builds per month.

That's significantly better than the ~170/month estimate 2 years ago: #15288 (comment).

I see it's also possible to configure ignored builds, can we only build previews when there are changes in the Doc directory? That would save resources and make PR runs quicker/cleaner too.

https://docs.netlify.com/configure-builds/ignore-builds/

[epicfaace]

I see it's also possible to configure ignored builds, can we only build previews when there are changes in the Doc directory? That would save resources and make PR runs quicker/cleaner too.

https://docs.netlify.com/configure-builds/ignore-builds/

This is already configured by default. The link above says "Depending on your Branches settings, any time there is a change in a linked repository, Netlify tries to determine whether there are changes in the site’s base directory by comparing the last known version of the files in that directory."

The base directory is already set to Doc/.

[hugovk]

Great, then I think we're all set!

---

@ewdurbin As a follow on to #15288 (comment) in 2019, we should now have 25k minutes per month (#82041 (comment)), and are ready to try this out again.

Please could you hook up the Netlify account? I would suggest we only run it on main to begin, and review usage after a few weeks/a month, and consider enabling it for 3.11 too (possibly even others).

---

If we have max 3 team members (#15288 (comment)), @Mariatta, you asked to be added in 2019 (#15288 (comment)), would you still like to?

And to further increase the bus factor, who would like to be the 3rd?

[epicfaace]

I'm happy to be the third! If it's fine though I'm not a committer

[epicfaace]

Also, looks like we're no longer limited to 3 team members max: see https://www.netlify.com/legal/open-source-policy/:

Our Open Source plan has the same features and limits as our Pro plan, with the addition of free unlimited team members.

[epicfaace]

Also, one more thing: I think to comply with the requirements mentioned in https://www.netlify.com/legal/open-source-policy/, we should add a Netlify badge / "This site is powered by Netlify" message on all deploy previews.

I don't think we need to / should add it to the main docs, but we can add it on deploy previews only -- for example, we could set an environment variable that then renders the Netlify badge only on deploy previews. I'm happy to implement if we're good with that approach. What do you think @hugovk ?

[hugovk]

The env var approach sounds good to add it only to deploy previews. Perhaps the text link option, in the footer? And just on the homepage or all pages?

[Mariatta]

Thanks for your work @epicface.

I think we need to display more prominently that the docs rendered is a "preview". So where-ever we put the netlify badge, we should add the "preview" info as well. Is that something we can do?

As comparison, on the devguide (built with readthedocs), the preview is displayed at the top of the page:

e.g: https://cpython-devguide--867.org.readthedocs.build/

[AA-Turner]

Adding a warning admonition to the top of the page seems a reasonable idea regardless, although the ephemeral nature of the previews (& non-canonical URL) should help to disambiguate d.p.o from the previews.

@hugovk from the linked Netifly page, it seems only the "main page" is required - so /index.html.

A

[hugovk]

Hi again @epicfaace! Do you think you can make the above changes? Thanks!

[arhadthedev]

I think the popup warning that collapses into the bottom will be more noticeable. Here is an example from tc39/ecma262:

[epicfaace]

Hi again @epicfaace! Do you think you can make the above changes? Thanks!

Yes, doing so!

@arhadthedev I like that idea. relevant code here: https://github.com/tc39/ecma262/blob/267fdbdc716677bc9934906a498cf9bad4bfb70d/scripts/snapshot_warning.htmlhttps://github.com/tc39/ecma262/blob/267fdbdc716677bc9934906a498cf9bad4bfb70d/scripts/insert_snapshot_warning.js and https://github.com/tc39/ecma262/blob/267fdbdc716677bc9934906a498cf9bad4bfb70d/scripts/snapshot_warning.css

[epicfaace]

All right, this PR should be ready now, @Mariatta and @hugovk . I just added a simple banner for now that displays on top of all pages:

Sample deploy preview: https://62af84a185fcf70008d07339--steady-heliotrope-731cac.netlify.app/

[hugovk]

Thanks, a couple of comments!

[hugovk]

Om mobile, the top of the banner is hidden:

[epicfaace]

Om mobile, the top of the banner is hidden:

Note that this banner uses the same styling as the "This document is for an old version of Python that is no longer supported" banner. The top of this banner will also be hidden once we start showing this banner on versions of the docs that have a responsive mobile layout. This means that when 3.8 reaches EOL (as 3.8 is the first version of the docs with a responsive mobile layout), we'll have a similar problem in which the top of the banner "This document is for an old version of Python that is no longer supported." will be hidden.

[epicfaace]

to clarify -- 3.6 doesn't have this problem as it's not using a mobile responsive layout:

but 3.8 most certainly will, once we add the red banner.

[hugovk]

Ah okay. So for the "no longer supported" it won't happen until 3.8 is EOL on 2024-10-14, but for the previews it will happen right away :)

We could report this to (I guess) https://github.com/python/python-docs-theme and come up with a fix later?

[epicfaace]

@hugovk yes. It seems more involved to fix that issue so I've went ahead and reported it in python/python-docs-theme#95.

[hugovk]

Thanks!

[hugovk]

@ewdurbin Hi! Please could you hook up the Netlify account again?

See #92852 (comment)

And please add @Mariatta to the team. Thank you!

[encukou]

@ewdurbin Will you be able to do this, or is something blocking you?

[hugovk]

Looks like we're all set now!

Here's a recent docs PR build:

• gh-87452 Making returncode unreliability explicit #92181

And the corresponding preview:

• And https://deploy-preview-92181--python-cpython-preview.netlify.app/

Thank you Ee for setting up Netlify and Ashwin for this and the earlier PRs! 👏

[encukou]

The banner is missing, though.

[hugovk]

I guess because that PR doesn't yet have the banner changes from this one.

@encukou Would you like to rebase/merge #100054 from main to test it?

[encukou]

You're right, with an up-to-date branch it works!

[Mariatta]

This is amazing! Thank you everyone for pushing through and thanks @epicfaace for this PR. This is a great help to all contributors here.

[epicfaace]

Amazing, thank you all for reviewing and getting this in!