Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Speeding up the Docs / Docs CI job #459

Closed
AA-Turner opened this issue Jun 7, 2022 · 7 comments
Closed

Speeding up the Docs / Docs CI job #459

AA-Turner opened this issue Jun 7, 2022 · 7 comments
Labels

Comments

@AA-Turner
Copy link
Member

AA-Turner commented Jun 7, 2022

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 job1, rather than a build with optimisation etc. Tests of my speed-up patch reduce the core docs job to ~3m15s2.

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 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.

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.

@AA-Turner
Copy link
Member Author

cc: @JulienPalard @ezio-melotti

@hugovk
Copy link
Member

hugovk commented Jun 7, 2022

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!

@AA-Turner
Copy link
Member Author

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

@AA-Turner AA-Turner added the CI label Jun 7, 2022
@methane
Copy link
Member

methane commented Jun 7, 2022

doctest in CI job should be run with HEAD Python.

@AA-Turner
Copy link
Member Author

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

@hugovk
Copy link
Member

hugovk commented Jun 7, 2022

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.

@AA-Turner
Copy link
Member Author

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

A

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Projects
None yet
Development

No branches or pull requests

3 participants