Skip to content

[Docs] add a new Sphinx VersionChange directive .. scheduled-changed:: #131733

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
XuehaiPan opened this issue Mar 25, 2025 · 2 comments
Closed

[Docs] add a new Sphinx VersionChange directive .. scheduled-changed:: #131733

XuehaiPan opened this issue Mar 25, 2025 · 2 comments
Labels
docs Documentation in the Doc dir pending The issue will be closed if no feedback is provided type-feature A feature request or enhancement

Comments

@XuehaiPan
Copy link
Contributor

Documentation

Follow the discussion in #127405 (comment):

No reason to actually use the word "deprecation" except to explain what process we're following for changing a user-visible and documented API.

The change is added in PR #131717:

   .. versionchanged:: 3.14
      A deprecation warning will be emitted if the :data:`sys.abiflags` member
      is accessed on Windows.

      The :data:`sys.abiflags` member will be set to a meaningful value on
      Windows in Python 3.16. This means the :data:`sys.abiflags` member will
      always be available on all platforms starting from Python 3.16.

A .. versionchanged:: directive is not very accurate for this change. It would be nice to have a new directive .. scheduled-changed:::

   .. scheduled-changed:: 3.14 3.16
      A deprecation warning will be emitted if the :data:`sys.abiflags` member
      is accessed on Windows.

      The :data:`sys.abiflags` member will be set to a meaningful value on
      Windows in Python 3.16. This means the :data:`sys.abiflags` member will
      always be available on all platforms starting from Python 3.16.

Like the .. deprecated-removed:: directive:

def setup(app: Sphinx) -> ExtensionMetadata:
# Override Sphinx's directives with support for 'next'
app.add_directive("versionadded", PyVersionChange, override=True)
app.add_directive("versionchanged", PyVersionChange, override=True)
app.add_directive("versionremoved", PyVersionChange, override=True)
app.add_directive("deprecated", PyVersionChange, override=True)
# Register the ``.. deprecated-removed::`` directive
app.add_directive("deprecated-removed", DeprecatedRemoved)

@XuehaiPan XuehaiPan added the docs Documentation in the Doc dir label Mar 25, 2025
@AA-Turner
Copy link
Member

I'm not sure I see the benefit, I would probably use a caution directive paired with a versionchanged for 3.14.

A

@AA-Turner AA-Turner added the pending The issue will be closed if no feedback is provided label Mar 25, 2025
@picnixz
Copy link
Member

picnixz commented Mar 28, 2025

I also think a caution would be better than a new directive (well, it could help in distinguishing these two when reading the rst but the online docs wouldn't see a difference IMO)

@picnixz picnixz added the type-feature A feature request or enhancement label Mar 28, 2025
@AA-Turner AA-Turner closed this as not planned Won't fix, can't repro, duplicate, stale Mar 28, 2025
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
docs Documentation in the Doc dir pending The issue will be closed if no feedback is provided type-feature A feature request or enhancement
Projects
Status: Todo
Development

No branches or pull requests

3 participants