◐ Shell
reader mode source ↗
Skip to content

gh-105373: Doc lists pending removals#106540

Merged
vstinner merged 1 commit into
python:mainfrom
vstinner:doc_pending_removals
Jul 9, 2023
Merged

gh-105373: Doc lists pending removals#106540
vstinner merged 1 commit into
python:mainfrom
vstinner:doc_pending_removals

Conversation

@vstinner

@vstinner vstinner commented Jul 8, 2023

Copy link
Copy Markdown
Member

@vstinner vstinner force-pushed the doc_pending_removals branch from aa6735b to a9316b0 Compare July 8, 2023 01:04
@vstinner

vstinner commented Jul 8, 2023

Copy link
Copy Markdown
Member Author

@hugovk, @CAM-Gerlach: Would you mind to review my documentation of this long list of deprecated features?

I'm not sure if all of them must be listed under "Pending Removal", since some of them are "incompatible changes" rather than "removals". But it seems like we have this habit in the previous What's New documents as well. So I continued the trend.

The phrasing is... minimal. Basically, I copied/pasted error messages from the code which emits DeprecationWarning. Example:

re: bad character in group name.

Maybe this entry should be elaborated... a little bit. Or removed. I'm not sure.


I had troubles with Sphinx syntax:

:func:`~!urllib.parse.splittype`

This fails with: WARNING: py:func reference target not found: !urllib.parse.splittype and the Docs job fails. But if I write:

:func:`!~urllib.parse.splittype`

I get a ~ in the rendered HTML! I gave up and used this syntax:

``splittype()``

I don't want to get a reference to this function... since it's not documented. And it should not be documented, since it's deprecated.


I also added "Pending Removals" under the C API Changes section in a previous commit.

@hugovk

hugovk commented Jul 8, 2023

Copy link
Copy Markdown
Member

Quick comment about Sphinx syntax, will come back to the rest:

``splittype()`` is fine, or you could use :func:`!splittype` - both will display as splittype() but with slightly different styling:

image

@vstinner vstinner merged commit 1e12c8c into python:main Jul 9, 2023
@vstinner vstinner deleted the doc_pending_removals branch July 9, 2023 15:26
@vstinner

vstinner commented Jul 9, 2023

Copy link
Copy Markdown
Member Author

I merged my PR to continue the work on the issue #105373. But please, don't hesitate to propose a PR to enhance this documentation, or leave post-merge comments on this PR.

@vstinner

Copy link
Copy Markdown
Member Author

Follow-up: PR #106675.

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 skip news

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants