Increase the build frequency of English HTML stable (and pre-release?) documentation #163
Description
It's come up a few times that increasing the frequency of builds for /3/ would be useful for core developers and contributors (potentially also /dev/ and the pre-release versions, but I'm happy to start small).
I'm led to believe that the expensive bit of the builds is the large matrix of versions and languages and the and the ePUB, PDF, etc, formats, so I wondered if it would be possible to configure a distinct task to regenerate only the English HTML documentation every e.g. 4 or 6 hours?
I believe that the config for this is located at https://github.com/python/psf-salt/blob/main/salt/docs/init.sls, though I'm not sure.
cc: @JulienPalard @hugovk @ezio-melotti for thoughts and comments
A
P.S.: I've tried a few times in the past to find out where the documentation build logs are, or at least to find out when the last rebuild was, without much success. The PSF-Salt docs have some information, and the docs themselves have a last built date (sans time) -- if anyone could point me in the right direction, I'd be very grateful!
Activity
hugovk commented on Sep 29, 2023
I'm supportive.
Once a day feels too infrequent for the English HTML docs, I'd like to see them built more frequently, maybe even triggering a deploy from merge.
But if on cron, perhaps we could do hourly, or every 15 minutes.
The download artifacts and translations could remain on a daily schedule.
I think it requires ssh access to the server?
It would be good to know the build times for various builds, and see the logs.
Adding the time would be a helpful addition.
AA-Turner commented on Sep 29, 2023
This at least is a quick fix: python/cpython#110091
A
JulienPalard commented on Sep 29, 2023
It was the case previously: python/psf-salt@38ee687
But building without PDF artifacts leads, at least on version bumps, to a few hours with HTML but without PDF.
This lead to spam on docs@ with people complaining about the absence of PDF (looks like they're used!).
See also: python/psf-salt@38ee687
See also: 1a0ad2e
AA-Turner commented on Sep 29, 2023
Is it possible to not delete the PDFs (ie save them and only refresh every 24h?)
JulienPalard commented on Oct 2, 2023
The problem is not about deleting PDFs, it's about them not being created at all during releases bumps.
It happen on every release (yearly major, but also each minor releases).
The PDF files has names like: https://docs.python.org/3.11/archives/python-3.11.5-docs-pdf-letter.zip
so when bumping from 3.11.5 to 3.11.6 if we only build HTML we're generating an HTML link to a non-existent PDF file.
I tried to mitigate this by displaying a nice 404 page, see:
https://docs.python.org/3.11/archives/python-3.11.999-docs-pdf-letter.zip
but it still lead to frustrated users and complains.
encukou commented on Oct 4, 2023
Would it be possible to make the 404 page link to the corresponding directory listing, like https://docs.python.org/3.11/archives/ ?
AA-Turner commented on Sep 25, 2024
xref python/docs-community#131
AA-Turner commented on Oct 2, 2024
Per python/docs-community#131 (comment), this has now been done.
A