◐ Shell
reader mode source ↗
Skip to content

Add a new Sphinx soft-deprecated directive#148630

Merged
hugovk merged 14 commits into
python:mainfrom
hugovk:3.15-docs-soft-deprecate-directive
Apr 18, 2026
Merged

Add a new Sphinx soft-deprecated directive#148630
hugovk merged 14 commits into
python:mainfrom
hugovk:3.15-docs-soft-deprecate-directive

Conversation

@hugovk

@hugovk hugovk commented Apr 15, 2026 •
edited by github-actions Bot
Loading

Copy link
Copy Markdown
Member

Follow on from #86519 and #148100.

Add a new Sphinx soft-deprecated directive, which explicitly links to the glossary definition, and is yellow instead of red because it does not indicate removal.

📚 Documentation preview 📚: https://cpython-previews--148630.org.readthedocs.build/

@hugovk hugovk requested a review from a team as a code owner April 15, 2026 20:20
@hugovk hugovk added the needs backport to 3.13 bugs and security fixes label Apr 15, 2026
@hugovk hugovk added the needs backport to 3.14 bugs and security fixes label Apr 15, 2026
@hugovk hugovk requested a review from StanFromIreland as a code owner April 15, 2026 20:20
@hugovk hugovk mentioned this pull request Apr 15, 2026
Closed
@hugovk hugovk added skip issue skip news docs Documentation in the Doc dir labels Apr 15, 2026
@github-project-automation github-project-automation Bot moved this to Todo in Docs PRs Apr 15, 2026
StanFromIreland
StanFromIreland reviewed Apr 15, 2026
View reviewed changes

@StanFromIreland StanFromIreland 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.

Hide comment

This is great Hugo, I also had been dreaming of this recently!

@ZeroIntensity

ZeroIntensity commented Apr 16, 2026

Copy link
Copy Markdown
Member

Would you mind also updating C API entries that only reference :term:`soft deprecated` (without the .. deprecated directive)? I decided not to use it when soft-deprecating things for #141004.

For example:

  1. https://docs.python.org/3/c-api/allocation.html#deprecated-aliases
  2. https://docs.python.org/3/c-api/file.html#deprecated-api
  3. https://docs.python.org/3/c-api/frame.html#legacy-local-variable-apis

I'm also happy to do this in a follow-up if you'd rather land this PR sooner.

@hugovk

hugovk commented Apr 16, 2026

Copy link
Copy Markdown
Member Author

@ZeroIntensity I've done those three, but there's quite a lot so I'll let you do the rest in a follow-up :) Alternatively, you're welcome to push to this branch or open a PR against mine.

29 hidden items Load more…
@StanFromIreland StanFromIreland mentioned this pull request Apr 17, 2026
Merged
StanFromIreland
StanFromIreland approved these changes Apr 17, 2026
View reviewed changes

@StanFromIreland StanFromIreland 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.

Hide comment

$${\color{purple}LGTM}$$!

We haven't covered all entries that are :term:`soft deprected` , but I think they can be done in follow ups.

@ZeroIntensity

ZeroIntensity commented Apr 18, 2026

Copy link
Copy Markdown
Member

Yeah, let's get this merged. I'll handle the remaining C API entries later.

Hide details View details @hugovk hugovk merged commit e9bbf86 into python:main Apr 18, 2026
34 checks passed
@hugovk hugovk deleted the 3.15-docs-soft-deprecate-directive branch April 18, 2026 08:37
@github-project-automation github-project-automation Bot moved this from Todo to Done in Docs PRs Apr 18, 2026
@miss-islington-app

miss-islington-app Bot commented Apr 18, 2026

Copy link
Copy Markdown

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

@miss-islington-app

miss-islington-app Bot commented Apr 18, 2026

Copy link
Copy Markdown

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

cherry_picker e9bbf8617dff942360b5d800769c00440dc93bac 3.14

@miss-islington-app

miss-islington-app Bot commented Apr 18, 2026

Copy link
Copy Markdown

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

cherry_picker e9bbf8617dff942360b5d800769c00440dc93bac 3.13

hugovk added a commit to hugovk/cpython that referenced this pull request Apr 18, 2026
@hugovk @StanFromIreland
[3.14] Add a new Sphinx soft-deprecated directive (pythonGH-148630) …
15cb0b9 
(cherry picked from commit e9bbf86)

Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com>
Co-authored-by: Stan Ulbrych <stan@python.org>
@hugovk hugovk mentioned this pull request Apr 18, 2026
Merged
@bedevere-app

bedevere-app Bot commented Apr 18, 2026

Copy link
Copy Markdown

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

@hugovk hugovk mentioned this pull request Apr 18, 2026
Merged
@bedevere-app

bedevere-app Bot commented Apr 18, 2026

Copy link
Copy Markdown

GH-148715 is a backport of this pull request to the 3.13 branch.

@bedevere-app bedevere-app Bot removed the needs backport to 3.13 bugs and security fixes label Apr 18, 2026
hugovk added a commit to hugovk/cpython that referenced this pull request Apr 18, 2026
@hugovk @StanFromIreland
[3.13] Add a new Sphinx soft-deprecated directive (pythonGH-148630) …
b9aa12f 
(cherry picked from commit e9bbf86)

Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com>
Co-authored-by: Stan Ulbrych <stan@python.org>
hugovk added a commit that referenced this pull request Apr 22, 2026
@hugovk @StanFromIreland
[3.14] Add a new Sphinx soft-deprecated directive (GH-148630) (#148714 …
5b33424 
)

Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com>
Co-authored-by: Stan Ulbrych <stan@python.org>
ljfp pushed a commit to ljfp/cpython that referenced this pull request Apr 25, 2026
@hugovk @StanFromIreland @ljfp
Add a new Sphinx soft-deprecated directive (python#148630) …
f960f2b 
Co-authored-by: Stan Ulbrych <stan@python.org>
hugovk added a commit that referenced this pull request Jun 14, 2026
@hugovk @StanFromIreland
[3.13] Add a new Sphinx soft-deprecated directive (GH-148630) (#148715 …
6971e05 
)

Co-authored-by: Stan Ulbrych <stan@python.org>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@picnixz picnixz picnixz left review comments

@StanFromIreland StanFromIreland StanFromIreland approved these changes

@ericsnowcurrently ericsnowcurrently Awaiting requested review from ericsnowcurrently ericsnowcurrently is a code owner

@ZeroIntensity ZeroIntensity Awaiting requested review from ZeroIntensity ZeroIntensity is a code owner

@AA-Turner AA-Turner Awaiting requested review from AA-Turner AA-Turner is a code owner

Assignees

@hugovk hugovk

Labels

docs skip issue skip news

Projects

Docs PRs
Status: Done

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

4 participants

@hugovk @ZeroIntensity @picnixz @StanFromIreland