Description

rob-neobim

opened on Dec 5, 2024

Issue body actions

Describe the bug

Each Python pre-release has a corresponding documentation archive. For example, 3.13.0a1 is located at python-3.13.0a1-docs-text.zip. Release versions are in a different location. For Python 3.14's pre-releases, these archives are missing. This has caused an issue for Chocolatey's Python 3 package, which uses these archives to populate the license and copyright information when automatically generating new releases. As a result, Windows users who install Python via Chocolatey cannot use either Python 3.13 or Python 3.14.

To Reproduce

1. Navigate to https://docs.python.org/3.14/archives/
2. Try to find the release-specific documentation archives for Python 3.14.0a1 and Python 3.14.0a2
3. Realise that they're not there

Expected behavior

The documentation archives should exist at the expected location.

URL to the issue

No response

Screenshots

No response

Browsers

Firefox, Chrome, Safari, Microsoft Edge, Other

Operating System

Windows

Browser Version

131.0.6778.86

Relevant log output

No response

Additional context

No response

Activity

1. rob-neobim

   added

   bugThis is a bug!This is a bug!

   on Dec 5, 2024
2. hugovk commented on Dec 5, 2024

   

   hugovk

   on Dec 5, 2024

   Member

   More actions

   Thanks for the report! Okay, let's see, there's a few things going on here.

   First of all, only release candidates and full releases have docs built as part of the official release, which is why we only find docs for RC and full releases at https://www.python.org/ftp/python/doc/

   This is detailed in PEP 101 ("Doing Python Releases 101"):

   • If this is a final or rc release (even a maintenance release), also unpack the HTML docs to /srv/docs.python.org/release/3.X.Y[rcA] on docs.nyc1.psf.io. Make sure the files are in group docs and are group-writeable.

   ---

   The docs you see for 3.13 alpha/beta/RCs in https://docs.python.org/3.13/archives/ are essentially a by-product of the docs build server, and aren't actually the docs of the tagged release.

   In PR python/cpython#124489, we stopped putting the major.minor version in these files, and this is why there's a recent x.y python-3.14-docs-text.zip in https://docs.python.org/3.14/archives/. The reasoning:

   "python-3.12.5-docs-pdf-a4.zip neither reflects the state of the documentation at the time of the 3.12.5 release nor necessarily the final state of the 3.12 docs prior to the 3.12.6 release; it's just what existed in the 3.12 git branch the last time the cron started building (and successfully finished) before the 3.12.6 release was merged into the 3.12 branch."

   By just using x.y we are honest that the download reflects the state of the website rather than any one release -- for that, use https://docs.python.org/release/.

   And this is also why https://docs.python.org/3.13/archives/ has a recently-created python-3.13-docs-text.zip, and there are no new versioned files after 25-Sep-2024. The above PR was merged the same day.

   We can also look in https://docs.python.org/3.12/archives/ and see a recent python-3.12-docs-text.zip, and that had made versioned files up to 3.12.6 on 24-Sep-2024.

   ---

   The issue for this PR included python/docs-community#131 (comment):

   We'll need to consider what to do with the existing /archives/ files. It likely doesn't hurt to keep them, even though they are in effect random snapshots of the documentation at some point in time. If we do remove them, we can create redirects in the docs server configuration so that links don't break.

   Perhaps we should remove them to make things a bit clearer here.

   ---

   To summarise, there are no official docs built for alpha and beta pre-releases. Release candidates and full releases do come with official docs builds.

   The ones you've been using so far aren't actually pre-release builds, but snapshots from some time around that version. You likely want to skip fetching docs for alphas and betas, unless you want to build the docs yourself from the tag, or make do with the recent x.y snapshot (which won't reflect the state of earlier tags).

   Does that help?

   Reacted by Rob Moss
3. robmoss2k commented on Dec 6, 2024

   

   robmoss2k

   on Dec 6, 2024

   More actions

   @hugovk - I cannot thank you enough for this. This all makes so much more sense now. We will need to rework things somewhat in the Python Chocolatey auto-update package, but it's always better not to operate under false assumptions. Hopefully, we can get Windows users back on the latest Python releases soon. Thanks again! Please feel free to close the issue, I consider myself fully resolved :)

   Reacted by Hugo van Kemenade
4. hugovk commented on Dec 6, 2024

   

   hugovk

   on Dec 6, 2024

   Member

   More actions

   You're welcome, happy to help :)
5. hugovk

   closed this as not plannedon Dec 6, 2024

Issue actions