Drop one of the two PDF sizes #128
Comments
I think this is important; we are not painstakingly typesetting a manual here. Reducing A4 paper to print on US Letter paper will have slightly more whitespace, but I think this trade-off is worth it. If a reader absolutely requires the US letter, it can still be built - we just won't provide it. I also agree that keeping the A4 paper version makes more sense out of the two. A |
|
Completely on board with producing only one size. I'm not sure how serious I am in suggesting dropping both and instead producing one with a custom size of 210x279 mm.
|
You're not the first to suggest letter height and A4 width! :) https://graphicdesign.stackexchange.com/a/38920/41266 But yeah, let's just pick one. Another option is dropping both PDFs and producing something like a single-file HTML instead (although we don't have a single PDF for the whole docs right now, we generate one PDF per section). NumPy dropped PDF entirely a few releases back (1.25, June 2023) -- https://numpy.org/doc/ -- and I hear they haven't had any problems. I expect building a single HTML should be much, much quicker than PDFs. As shown above, the current HTML takes ~3 minutes, a full build takes 0.5-2 hours and is mostly PDF building. But we do get the occasional bug report about PDFs so I'm not proposing this (at least not just yet ;) |
I agree dropping Letter and keeping A4.
I'd say that people that want to print it will probably built their own PDF version adding a lot of effort on top of the preliminary LaTeX version outputted by Sphinx. We usually print just the tutorial for Python Argentina and we created a whole project for that to get a print-quality book: https://github.com/PyAr/tutorial-en-papel That said, I wouldn't worry too much about "people wanting to print it" because they would probably do something different by themselves.
In my experience, this could be an issue when the resulting file is too big --in particular with memory issues. If you have the chance to give it a quick try, that would be good data to know how it performs in the current servers. |
|
Building Opening the print dialog in Chrome shows "Loading preview..." for a few seconds before the tab crashes with "Aw, Snap!". So a headless browser could be the way for that. |
|
We'd at least need the following to drop letter PDF.
We'd need to coordinate backports of (1) to make sure the release scripts don't wait indefinitely for letter PDF files that will never show up, and/or include a version check in (2). Anything else? |
It seems like (2) could go first, and (1) backports can then be done at leisure? The release script is looking for files that are produced after |
|
Here's (2): python/release-tools#168 |
|
Completely agree with dropping Letter PDF. I would be fine at some point following Numpy's lead and dropping A4 PDF too. It seems environmentally wasteful to run for hours. |
|
Here's (1): python/cpython#123912 |
|
They're both merged for 3.14/ We've had a 3.14 batch built and https://docs.python.org/3.14/download.html only lists a single PDF which is the A4 ones, as expected.
However, there are still old letter versions on the server from the last time they were built:
Confirming by logging into the docs build server: hugovk@docs:/mnt/volume_nyc3_07/docs.python.org$ ll 3.14/archives/python-3.14.0a0-docs-pdf-letter.zip
-rw-rw-r-- 1 docsbuild docs 18886596 Sep 12 16:56 3.14/archives/python-3.14.0a0-docs-pdf-letter.zip
hugovk@docs:/mnt/volume_nyc3_07/docs.python.org$ ll 3.14/archives/python-3.14.0a0-docs-pdf-a4.zip
-rw-rw-r-- 1 docsbuild docs 18728661 Sep 15 10:48 3.14/archives/python-3.14.0a0-docs-pdf-a4.zipWe don't want to keep serving out-of-date letter files, so I'll manually delete them (or move them to my home dir for a while), then we can do the backports, and repeat for those. Sounds good? |
|
Done, tested with hugovk@docs:/mnt/volume_nyc3_07/docs.python.org$ rsync --archive --verbose --prune-empty-dirs --include='*/' --include='python-3.14.0a0-docs-pdf-letter.*' --exclude='*' --remove-source-files /mnt/volume_nyc3_07/docs.python.org ~/letter-pdfs/
building file list ... done
docs.python.org/
docs.python.org/3.14/
docs.python.org/3.14/archives/
docs.python.org/3.14/archives/python-3.14.0a0-docs-pdf-letter.tar.bz2
docs.python.org/3.14/archives/python-3.14.0a0-docs-pdf-letter.zip
docs.python.org/es/
docs.python.org/es/3.14/
docs.python.org/es/3.14/archives/
docs.python.org/es/3.14/archives/python-3.14.0a0-docs-pdf-letter.tar.bz2
docs.python.org/es/3.14/archives/python-3.14.0a0-docs-pdf-letter.zip
docs.python.org/fr/
docs.python.org/fr/3.14/
docs.python.org/fr/3.14/archives/
docs.python.org/fr/3.14/archives/python-3.14.0a0-docs-pdf-letter.tar.bz2
docs.python.org/fr/3.14/archives/python-3.14.0a0-docs-pdf-letter.zip
docs.python.org/id/
docs.python.org/id/3.14/
docs.python.org/id/3.14/archives/
docs.python.org/id/3.14/archives/python-3.14.0a0-docs-pdf-letter.tar.bz2
docs.python.org/id/3.14/archives/python-3.14.0a0-docs-pdf-letter.zip
docs.python.org/it/
docs.python.org/it/3.14/
docs.python.org/it/3.14/archives/
docs.python.org/it/3.14/archives/python-3.14.0a0-docs-pdf-letter.tar.bz2
docs.python.org/it/3.14/archives/python-3.14.0a0-docs-pdf-letter.zip
docs.python.org/ja/
docs.python.org/ja/3.14/
docs.python.org/ja/3.14/archives/
docs.python.org/ja/3.14/archives/python-3.14.0a0-docs-pdf-letter.tar.bz2
docs.python.org/ja/3.14/archives/python-3.14.0a0-docs-pdf-letter.zip
docs.python.org/ko/
docs.python.org/ko/3.14/
docs.python.org/ko/3.14/archives/
docs.python.org/ko/3.14/archives/python-3.14.0a0-docs-pdf-letter.tar.bz2
docs.python.org/ko/3.14/archives/python-3.14.0a0-docs-pdf-letter.zip
docs.python.org/pl/
docs.python.org/pl/3.14/
docs.python.org/pl/3.14/archives/
docs.python.org/pl/3.14/archives/python-3.14.0a0-docs-pdf-letter.tar.bz2
docs.python.org/pl/3.14/archives/python-3.14.0a0-docs-pdf-letter.zip
docs.python.org/pt-br/
docs.python.org/pt-br/3.14/
docs.python.org/pt-br/3.14/archives/
docs.python.org/pt-br/3.14/archives/python-3.14.0a0-docs-pdf-letter.tar.bz2
docs.python.org/pt-br/3.14/archives/python-3.14.0a0-docs-pdf-letter.zip
docs.python.org/tr/
docs.python.org/tr/3.14/
docs.python.org/tr/3.14/archives/
docs.python.org/tr/3.14/archives/python-3.14.0a0-docs-pdf-letter.tar.bz2
docs.python.org/tr/3.14/archives/python-3.14.0a0-docs-pdf-letter.zip
docs.python.org/zh-cn/
docs.python.org/zh-cn/3.14/
docs.python.org/zh-cn/3.14/archives/
docs.python.org/zh-cn/3.14/archives/python-3.14.0a0-docs-pdf-letter.tar.bz2
docs.python.org/zh-cn/3.14/archives/python-3.14.0a0-docs-pdf-letter.zip
docs.python.org/zh-tw/
docs.python.org/zh-tw/3.14/
docs.python.org/zh-tw/3.14/archives/
docs.python.org/zh-tw/3.14/archives/python-3.14.0a0-docs-pdf-letter.tar.bz2
docs.python.org/zh-tw/3.14/archives/python-3.14.0a0-docs-pdf-letter.zip
sent 517,389,459 bytes received 1,308 bytes 206,956,306.80 bytes/sec
total size is 517,015,797 speedup is 1.00Next, backports for (1). I've merged the 3.12 backport: python/cpython#123999. Please could I have a core dev review for the 3.13 backport (because of the RC)? python/cpython#123998 |
At this point you need Thomas, not just another core dev :). 3.13 is locked until 3.13.0 final. |
|
Yup, but I think it'll help Thomas if it's already had a second reviewer by the time he checks it (and the other 48 pending PRs). And if I've missed something, I can update it right now, before Thomas get around to it. |
|
Comparing a set of 3.14 builds from before dropping letter PDF:
With this morning, after dropping letter PDF (for a fair comparison, removing
That's 1.6 times as fast, saving about 5 hours per version set, and about 15 hours for the whole loop! |
|
python/cpython#123998 has been merged; the final PR. A |
Helps python/docsbuild-scripts#169.
A full docs build cycle takes about 40 hours to build all versions × languages:
https://github.com/hugovk/last-updated/actions/runs/10689864099/job/29632960987#step:7:44
Here's one cycle:
The Ukrainian ones are HTML-only and take 3-4 minutes. The others build a full set and take somewhere between 30 minutes - 2 hours.
Most of this time is spent building PDFs. Looking at the numbers at python/docsbuild-scripts#169, from building locally, about 83% is building both the A4 and US Letter PDFs.
The A4 and Letter PDFs each take about the same time to build.
I don't think we need to build two different PDF sizes.
I expect many who download a PDF will use it on a device screen, and a slight aspect difference won't make much difference. And for people who also print them, it shouldn't matter too much either: PDF viewers can auto-resize to fit the local paper. These files haven't been carefully laid out, they're autogenerated so we don't need pixel-perfect output.
I propose we drop one of the two PDF formats, which should save us a huge amount of build time, let us get other docs builds out faster.
I don't mind which one, but I'll suggest dropping Letter, used in the US and Canada, and keeping A4, an international standard used globally.
A rough calculation shows this would decrease a full build cycle from around 40 hours to 24 hours.
Thoughts?
The text was updated successfully, but these errors were encountered: