[StanFromIreland]

Sphinx 9.1.1 was recently released, and it fixed the previous blockers for us using Sphinx 9. Let's try it!

Please test the RtD preview and let me know if there are any issues!

[read-the-docs-community]

Documentation build overview

📚 cpython-previews | 🛠️ Build #35544910 | 📁 Comparing 866f968 against main (f5bd077)

  🔍 Preview build  

148 files changed · + 1 added · ± 147 modified

+ Added

• c-api/pyexpat.html

± Modified

• glossary.html
• license.html
• builtins/exceptions.html
• builtins/functions.html
• builtins/stdtypes.html
• c-api/bool.html
• c-api/buffer.html
• c-api/bytes.html
• c-api/code.html
• c-api/codec.html
• and 137 more...

[hugovk]

Converting to draft while the 14 day cooldown is in effect:

cpython/Doc/Makefile

Line 191 in 377146f

# Dependencies have a 14 day cooldown period to mitigate supply chain attacks,

But please test the preview in the meantime :)

[AA-Turner]

except for blurb, python-docs-theme, and sphinx_linklint, which are maintained by core team members

Sphinx is also maintained by (multiple) core developers... would it make more sense to do case-by-case exclusions where a newer version than a fortnight ago is needed?

A

[hugovk]

By multiple core devs, and also multiple others :) I have security on my mind right now, so prefer to err on the cautious.

It's a long time since the last release, but I don't think we're waiting on anything in particular, other than upgrading to keep current, so don't need to rush?

[StanFromIreland]

Two weeks have passed.

[picnixz]

This may sound stupid, but I think it'd be good if we announce those changes in NEWS entries. Now that people are more aware of version pinning, they may want to know in advance what will happen for upgrades.

[StanFromIreland]

Hmm, could you please elaborate a little as to who the target audience would be? I presume distributors use what we have pinned, rather than maintaining a separate pinned set.

[picnixz]

It's just about knowing that and being updated online in advance. But if we didn't do it for the past updates, no need to do it for this one. However, the changelogs contain mentions of updates in general (e.g. #125722 or #125277).

[picnixz]

I guess since we also had issues in the past, I suggest you to create the issue as well (if it's not already the case)

[StanFromIreland]

I attached it to the PR, I'm not sure there's additional benefit of an issue here?

[picnixz]

I meant a real issue. Like we did for every past updates for Sphinx.

[picnixz]

It's also a good idea to know why we are updating (for posterity).

[hugovk]

I don't think this needs a NEWS entry (or issue).

But if we didn't do it for the past updates, no need to do it for this one.

We didn't do it for the past updates, going back three years:

• Docs: Upgrade Sphinx to 9.0 #142114
• Docs: Upgrade Sphinx to 8.2 #130171
• Doc: Upgrade Sphinx to 8.1 #125276
• Docs: bump Sphinx to 8.0 and update constraints #122496
• Docs: Upgrade Sphinx to 7.4 #121987
• Docs: Upgrade to Sphinx 7.3 #118397
• GH-99380: Update to Sphinx 7 #99381
• Docs: upgrade to python-docs-theme 2023.7 #107617

However, the changelogs contain mentions of updates in general (e.g. #125722 or #125277).

Those issues are from when we were being extremely cautious about upgrading and checking downstream versions, and about being able to backport.

[picnixz]

Ah! sorry for being overly-pedantic then. However, can you add either in the commit message or the PR description why we eventually updated to 9.1.1? (I think it was primarly to fix the chinese translations? or was it for something else?)

Actually we released 9.2 during the sprint I think, and I don't remember whether it's 9.1.1 which includes the translation fix by Hugo or if it's 9.2. I suppose we could directly update to 9.2 assuming Adam plans to do a 9.3 soon?

[AA-Turner]

No immediate plans for 9.3 soon -- 9.2 is mainly just version bumps so I think either 9.1.1 or 9.2 would be fine.

A

[StanFromIreland]

I think it was primarly to fix the chinese translations? or was it for something else?

It's primarily to keep the version current, the Chinese translation search bug prevented us from upgrading to Sphinx 9 previously, but that is addressed in 9.1.1. Additionally, it would fix #159265, but that's a rather minor issue.