Skip to content

gh-155095: Fix docs changes builder for our custom directives - #155100

Merged
StanFromIreland merged 2 commits into
python:mainfrom
StanFromIreland:changes-build-and-render
Sep 12, 2026
Merged

gh-155095: Fix docs changes builder for our custom directives#155100
StanFromIreland merged 2 commits into
python:mainfrom
StanFromIreland:changes-build-and-render

Conversation

@StanFromIreland

@StanFromIreland StanFromIreland commented Aug 2, 2026 •
edited by bedevere-app Bot
Loading

Copy link
Copy Markdown
Member

We need to extend ChangesBuilder's typemap with entries for our custom soft-deprecated and deprecated-removed directives (the latter was accidentally ignored). We need a little helper, _fixup_changeset as the changeset text is recorded before the directive replaces the marker with a glossary reference so the soft deprecated text is rendered incorrectly (":term:`Soft deprecated` ..."). It also includes some additional handling for deprecated-removed so that deprecations and removals are indexed separately.

This does not fix the missing yellow source-line highlighting in the builder's source view, which uses a separate hard-coded directive list in Sphinx:

https://github.com/sphinx-doc/sphinx/blob/9af5b469df42c810c62453661c1974c0f254e674/sphinx/builders/changes.py#L118-L127

It should be fixed upstream (by changing hltext to be derived from from typemap), as I don't think that adding logic to inject highlighting after the view is built or re-writing the builder is worth it for this.

@bedevere-app bedevere-app Bot mentioned this pull request Aug 2, 2026
Closed
@StanFromIreland

StanFromIreland commented Sep 10, 2026

Copy link
Copy Markdown
Member Author

Little ping @hugovk :-)

hugovk
hugovk approved these changes Sep 11, 2026
View reviewed changes

@hugovk hugovk left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Shall we also add a make changes to the CI after the main docs build to ensure this keeps working in the future? It will be quick, especially after the main build.

@StanFromIreland

StanFromIreland commented Sep 11, 2026

Copy link
Copy Markdown
Member Author

Shall we also add a make changes to the CI after the main docs build to ensure this keeps working in the future?

Since it's only a few seconds, I think that's reasonable. Although I doubt many people use this feature.

@read-the-docs-community

read-the-docs-community Bot commented Sep 11, 2026

Copy link
Copy Markdown

Documentation build overview

📚 cpython-previews | 🛠️ Build #34512398 | 📁 Comparing da46dc7 against main (204feba)

  🔍 Preview build  

126 files changed · + 1 added · ± 125 modified

+ Added

± Modified

@StanFromIreland
StanFromIreland merged commit 94dc051 into python:main Sep 12, 2026
30 checks passed
@StanFromIreland
StanFromIreland deleted the changes-build-and-render branch September 12, 2026 09:11
@StanFromIreland StanFromIreland added needs backport to 3.13 bugs and security fixes needs backport to 3.14 bugs and security fixes labels Sep 12, 2026
@miss-islington-app

miss-islington-app Bot commented Sep 12, 2026

Copy link
Copy Markdown

Thanks @StanFromIreland for the PR 🌮🎉.. I'm working now to backport this PR to: 3.13.
🐍🍒⛏🤖

@miss-islington-app

miss-islington-app Bot commented Sep 12, 2026

Copy link
Copy Markdown

Thanks @StanFromIreland for the PR 🌮🎉.. I'm working now to backport this PR to: 3.14.
🐍🍒⛏🤖

@miss-islington-app

miss-islington-app Bot commented Sep 12, 2026

Copy link
Copy Markdown

Sorry, @StanFromIreland, I could not cleanly backport this to 3.13 due to a conflict.
Please backport using cherry_picker on command line.

cherry_picker 94dc05133531d792fb0e14bfe12c3fe65ba3a91f 3.13

@miss-islington-app

miss-islington-app Bot commented Sep 12, 2026

Copy link
Copy Markdown

Sorry, @StanFromIreland, I could not cleanly backport this to 3.14 due to a conflict.
Please backport using cherry_picker on command line.

cherry_picker 94dc05133531d792fb0e14bfe12c3fe65ba3a91f 3.14

@bedevere-app

bedevere-app Bot commented Sep 12, 2026

Copy link
Copy Markdown

GH-157357 is a backport of this pull request to the 3.14 branch.

@bedevere-app bedevere-app Bot removed the needs backport to 3.14 bugs and security fixes label Sep 12, 2026
StanFromIreland added a commit that referenced this pull request Sep 12, 2026
@StanFromIreland
[3.14] gh-155095: Fix docs changes builder for our custom directives (G…
b9f6d5a 
…H-155100) (#157357)

(cherry picked from commit 94dc051)
@StanFromIreland StanFromIreland added needs backport to 3.15 pre-release feature fixes, bugs and security fixes and removed needs backport to 3.13 bugs and security fixes labels Sep 12, 2026
@miss-islington-app

miss-islington-app Bot commented Sep 12, 2026

Copy link
Copy Markdown

Thanks @StanFromIreland for the PR 🌮🎉.. I'm working now to backport this PR to: 3.15.
🐍🍒⛏🤖

@bedevere-app

bedevere-app Bot commented Sep 12, 2026

Copy link
Copy Markdown

GH-157359 is a backport of this pull request to the 3.15 branch.

@bedevere-app bedevere-app Bot removed the needs backport to 3.15 pre-release feature fixes, bugs and security fixes label Sep 12, 2026
StanFromIreland added a commit that referenced this pull request Sep 12, 2026
@miss-islington @StanFromIreland
[3.13] gh-155095: Fix docs changes builder for our custom directives (G…
0a7db33 
…H-155100) (GH-157357) (#157358)

(cherry picked from commit 94dc051)

Co-authored-by: Stan Ulbrych <stan@python.org>
hugovk pushed a commit that referenced this pull request Sep 12, 2026
@miss-islington @StanFromIreland
[3.15] gh-155095: Fix docs changes builder for our custom directives (G…
6241129 
…H-155100) (#157359)

gh-155095: Fix docs changes builder for our custom directives (GH-155100)
(cherry picked from commit 94dc051)

Co-authored-by: Stan Ulbrych <stan@python.org>
clin1234 pushed a commit to clin1234/cpython that referenced this pull request Sep 12, 2026
@StanFromIreland @clin1234
pythongh-155095: Fix docs changes builder for our custom directives (p…
063051a 
…ython#155100)
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@hugovk hugovk hugovk approved these changes
@JacobCoffee JacobCoffee JacobCoffee approved these changes
@AA-Turner AA-Turner Awaiting requested review from AA-Turner AA-Turner is a code owner
@ezio-melotti ezio-melotti Awaiting requested review from ezio-melotti ezio-melotti is a code owner
@webknjaz webknjaz Awaiting requested review from webknjaz webknjaz is a code owner
@itamaro itamaro Awaiting requested review from itamaro itamaro is a code owner

Assignees

@StanFromIreland StanFromIreland

Labels

skip news

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

3 participants

@StanFromIreland @hugovk @JacobCoffee