Manually running a rebuild

[AA-Turner]

We should write down the steps to properly running a rebuild, e.g. on release day or for end-of-life versions. I ran the rebuild on Monday to ensure that /3/ was promptly updated, but there was no process to follow.

Likewise, for versions that become unsupported, we should trigger one final rebuild so that the "outdated" header/warning is added. For example, we need to do this now with https://docs.python.org/3.8/.

cc @JulienPalard -- I'm not sure how you've handled this in the past (especially EOL versions), and if there is a process you would recommend?

A

[AA-Turner]

Friendly ping @JulienPalard -- would it be best to say that manual builds are unsupported perhaps? The Python 3.8 docs still lack the "outdated" banner, so I'm not sure what the best method would be here.

A

[hugovk]

Manual builds are needed EOL and security branches, for example:

• Full build with PDF is taking more than 24h #169 (comment)
• 3.11 documentation has no changelog entry for 3.11.9 cpython#121484 (comment)

And it's part of PEP 101 for EOL transitions:

Add a retired notice to each release page on python.org for the retired branch.

https://peps.python.org/pep-0101/#moving-to-end-of-life

I agree we should write down the steps on how to actually perform a manual build.

[JulienPalard]

(Yeah I'm under 500 unread github notifications \o/)

For manual rebuild I do:

$ ssh docs.nyc1.psf.io
$ screen -DUR
$ sudo su --shell=/bin/bash docsbuild
$ /srv/docsbuild/venv/bin/python /srv/docsbuild/scripts/build_docs.py --branch 3.8

That's not ideal, but that's not often needed.

Sometimes killing a running build is needed so the manual one can start :D

I just started the rebuild for 3.8.

[JulienPalard]

3.8 rebuild done.

[hugovk]

Hmm, https://docs.python.org/3.8/ is still missing the banner and says "Last updated on Sep 08, 2024".

[hugovk]

3.8 is still waiting for a rebuild, and we now also need rebuilds for the 3.9-3.11 security branches:

• https://discuss.python.org/t/python-3-13-1-3-12-8-3-11-11-3-10-16-and-3-9-21-are-now-available/73214
• 3.11 documentation has no changelog entry for 3.11.9 cpython#121484 (comment)

I've kicked off a 3.11 build using the instructions above 🤞

[hugovk]

3.11 finished!

2024-12-07 11:37:08,426 INFO: Full build done (16h 18m 2s).

I've started 3.10, but opened the screen under the docsbuild user instead of my own:

ssh docs.nyc1.psf.io
sudo su --shell=/bin/bash docsbuild
screen -DUR
/srv/docsbuild/venv/bin/python /srv/docsbuild/scripts/build_docs.py --branch 3.10

screen -DUR will either create a new screen session, or if there's already one running, it'll connect you to it. So others with server access can also check on the progress.

[hugovk]

3.10 finished!

2024-12-08 00:38:35,718 INFO: Full build done (12h 49m 46s).

3.9 started.

[hugovk]

It would be useful to be able to manually build a bunch of these with a single command in the future, like:

/srv/docsbuild/venv/bin/python /srv/docsbuild/scripts/build_docs.py --branch 3.11 3.10 3.9 3.8

Please see PR #235.

[hugovk]

3.9 finished!

2024-12-09 09:35:58,914 INFO: Full build done (15h 18m 37s).

And now let's retry 3.8.

[hugovk]

Please see PR #236 to add the instructions to RELEASING.md.