Description

AA-Turner

opened on Jun 7, 2022

Issue body actions

The short story

I think the Docs CI job can be faster, which would improve the contribution and review experience.

Long version

In the documentation team meeting we've been talking about a few workflow improvements. The Docs / Docs CI job is quite slow, taking around 15-20 minutes. From some quick testing, it seems this is largely due to that we use Python from HEAD and build Python in the job¹, rather than a build with optimisation etc. Tests of my speed-up patch reduce the core docs job to ~3m15s².

As a reviewer, a green tick is a quick signal that the syntax of the documentation is probably correct, and I don't need to be as thorough, whereas if the build fails I can look in the logs and point out the error and a potential fix to the proponenet of the PR.

I would suggest moving to actions/setup-python for the Docs job, but I don't know if there's been prior discussion³ on this that I haven't been able to find, or if there are other reasons it makes sense to trade off speed for building Python from HEAD.

A

Footnotes

1. https://github.com/python/cpython/actions/workflows/doc.yml ↩

2. Patch, Run 1, Run 2, Run 3. ↩

3. Find a way to avoid redundant CI workflow builds of cpython just to test Docs #435 discusses not building Python, but in the context of reusing another build from HEAD rather than an optimised version. ↩

Reacted by Ezio Melotti and Alex Waygood

Activity

1. AA-Turner commented on Jun 7, 2022

   

   AA-Turner

   on Jun 7, 2022

   MemberAuthor

   More actions

   cc: @JulienPalard @ezio-melotti
2. hugovk commented on Jun 7, 2022

   

   hugovk

   on Jun 7, 2022

   Member

   More actions

   cc @ned-deily re: #435

   ---

   I would suggest moving to actions/setup-python for the Docs job, but I don't know if there's been prior discussion3 on this that I haven't been able to find, or if there are other reasons it makes sense to trade off speed for building Python from HEAD.

   actions/setup-python also suggested at #429 (comment), with three 👍.

   ---

   The big question is: do we need to build docs against Python from HEAD?

   • One reason to build from source (or with a recent build): to see deprecations.

   If not, I think using actions/setup-python is a great idea.

   And we have options of what Python to test with [with approx setup timings]:

   1. [~2s] Default, a recent Python 3 release (as in the patch, currently 3.10.4)
   2. [~2s] Explicitly setting a stable version e.g. 3.10
   3. [~14s] Explicitly setting a dev version e.g. 3.11-dev is the latest alpha/beta/RC release
   4. [~32s] Alternatively, use https://github.com/deadsnakes/action to test a nightly build, e.g. 3.11-dev, 3.12-dev (for example)

   Building Python from source takes about 141s, so the above options are quite a bit quicker.

   ---

   But the patch saves much more time than ~141s in setup though.

   • One reason is it splits the two build into two parallel jobs, docs build on actions/setup-python, and doctest on HEAD (as new syntax doesn't exist in the latest stable release).

   The real big saving:

   • The docs build ("Build HTML documentation" step) with actions/setup-python takes only ~2m compared to 6-15m with Python on HEAD!

   Reacted by Adam Turner
3. AA-Turner commented on Jun 7, 2022

   

   AA-Turner

   on Jun 7, 2022

   MemberAuthor

   More actions

   Thanks for finding the comment from #429!

   One reason to build from source (or with a recent build): to see deprecations

   I think this is a less compelling reason -- the Sphinx project tests with the latest development builds (currently deadsnakes' 3.11-dev nightly builds), so will catch deprecations there. Were there non-Sphinx deprecations you were referring to? (The link was to the collapsed summary page, so I'm not sure which deprecation warnings you're talking about).

   A
4. AA-Turner

   added

   CI

   on Jun 7, 2022
5. methane commented on Jun 7, 2022

   

   methane

   on Jun 7, 2022

   Member

   More actions

   doctest in CI job should be run with HEAD Python.

   Reacted by Zachary Ware
6. AA-Turner commented on Jun 7, 2022

   

   AA-Turner

   on Jun 7, 2022

   MemberAuthor

   More actions

   doctest in CI job should be run with HEAD Python.

   @methane -- in my patch the jobs are split so that doctest still runs on HEAD -- is this alright?

   A

   Reacted by Inada Naoki
7. hugovk commented on Jun 7, 2022

   

   hugovk

   on Jun 7, 2022

   Member

   More actions

   I think this is a less compelling reason -- the Sphinx project tests with the latest development builds (currently deadsnakes' 3.11-dev nightly builds), so will catch deprecations there. Were there non-Sphinx deprecations you were referring to? (The link was to the collapsed summary page, so I'm not sure which deprecation warnings you're talking about).

   Agreed, if they're just from third-party libraries it's not important. Much better to speed up the builds.

   Reacted by Adam Turner
8. AA-Turner commented on Jun 15, 2022

   

   AA-Turner

   on Jun 15, 2022

   MemberAuthor

   More actions

   python/cpython#93736 has been merged, thanks all.

   A

   Reacted by Alex Waygood, Hugo van Kemenade and Ezio Melotti
9. AA-Turner

   closed this as completedon Jun 15, 2022

Issue actions