GeezerVison

How will this work in a translation, _add_glossary_link sets marker = "Soft deprecated"?

Also, you'll have to add the message to dummy.html for it to be extracted IIRC.

How will this work in a translation, _add_glossary_link sets marker = "Soft deprecated"?

I just pushed bee4f6c, I think that might do it?

Also, you'll have to add the message to dummy.html for it to be extracted IIRC.

Thanks, added.

I think that might do it?

It will do it for Polish, but I worry in other languages it might not (I fear it is possible in some there may be a slight difference between the term's stand-alone form and it in a sentence).

This standalone text is only used for replacing in the full sentence, and not used on its own. So each translation will need to put whatever they have in the sentence.

Yes, but how are translators supposed to know that?

Shall we add a comment in Doc/tools/templates/dummy.html?

Translators won't see it unfortunately, Sphinx doesn’t support adding comments for translators. Can we have :term:`soft deprecated` in the string?

I wrote hugovk#81.

We use yellow for versionchanged and thread safety notes, I worry they all look a little too similar. I would suggest it gets its' own styling, maybe orange?

Hmm, yellow is more of a "heads up, note this". Orange might be considered closer to "red for danger", and we don't want to suggest it's going away.

Hmm, yellow is more of a "heads up, note this". Orange might be considered closer to "red for danger", and we don't want to suggest it's going away.

Indeed, but we also want it to stand out compared to other notes (at least that's what I think). Some functions have quite long lists of yellow change notes that, e.g. I often ignore when just looking for current information about a thing, and would probably miss a soft deprecation note at the end. We aren't removing it, but we also don't want people using it.

We use green for additions, yellow for changes and red for deprecations so I would suggest using blue/purple for soft deprecation. A soft deprecation is a change, but not one that screams "I am new!" or "I am bad" but rather "please note this".

To have the same color on both themes, I would go with 3b82f6 or 1e6ff5.

Here's the current, #3b82f6 and #1e6ff5 for each theme:

If we change the colour, we'll override it via https://github.com/python/python-docs-theme.

I like Bénédikt's purple (rgb(175, 0, 255) below) suggestion, but blue is alright:

I'm not so keen on purple, and the contrast ratio is too low for dark mode:

Oh I see, that's not ideal. I also checked #3b82f6 and neither dark (4.33) nor light (3.68) meet the requirements. Similarly for #1e6ff5, it meets the requirements only in light (4.52) and not in dark (3.52).

Yeah, we can use different colours for light and dark. Anyway, we can bikeshed that in the theme.

I wrote python/python-docs-theme#305.

ERROR: Removed IDs found
The above HTML IDs were removed from the documentation, resulting in broken links. Please add them back.
c-api/allocation.html: deprecated-aliases

c-api/file.html: deprecated-api

Alternatively, add them to Doc/tools/removed-ids.txt.

This change was intentional as it makes it explicit these aren't going away, and the header is new in 3.15.

Shall I:

• Add ref deprecated-alises just above it
• Add to Doc/tools/removed-ids.txt
• Revert

Seeing as it's quite new I think it is unlikely we're breaking anyone’s reference. So, I suggest we create a "remove from here in 3.16" section in removed-ids.txt for such changes.

Feedback for the tool output:

The above HTML IDs were removed from the documentation, resulting in broken links. Please add them back.
c-api/allocation.html: deprecated-aliases

c-api/file.html: deprecated-api

Alternatively, add them to Doc/tools/removed-ids.txt.

"above" should read "below". Can improve spacing to make both warnings more obvious:

The below HTML IDs were removed from the documentation, resulting in broken links. Please add them back.

c-api/allocation.html: deprecated-aliases
c-api/file.html: deprecated-api

Alternatively, add them to Doc/tools/removed-ids.txt.

"above" should read "below". Can improve spacing to make both warnings more obvious:

"above" is technically correct IIRC (from when I tried to add color), it is just GitHub mangling stdout/err and the line ends up above. We should have an issue for further improvements.

Hmm, indeed, we can have different output:

ERROR: Removed IDs found
The above HTML IDs were removed from the documentation, resulting in broken links. Please add them back.
c-api/allocation.html: deprecated-aliases

c-api/file.html: deprecated-api

Alternatively, add them to Doc/tools/removed-ids.txt.

https://github.com/python/cpython/actions/runs/24515704242/job/71659379442?pr=148630

ERROR: Removed IDs found
c-api/allocation.html: deprecated-aliases
The above HTML IDs were removed from the documentation, resulting in broken links. Please add them back.

c-api/file.html: deprecated-api

Alternatively, add them to Doc/tools/removed-ids.txt.

https://github.com/python/cpython/actions/runs/24517209594/job/71664949402?pr=148630

After ignoring file.html:

ERROR: Removed IDs found
c-api/allocation.html: deprecated-aliases
The above HTML IDs were removed from the documentation, resulting in broken links. Please add them back.

Alternatively, add them to Doc/tools/removed-ids.txt.

https://github.com/python/cpython/actions/runs/24521766250/job/71681524452?pr=148630

@ZeroIntensity This section was first added to docs in #141146 and backported to 3.13.

That PR said:

There are already deprecated, so this can be backported.

That links to code from PR #23586, which deprecated them in code comments in 3.10.

So, should this say 3.15 or 3.10 or something else?

A 'lil ping @ZeroIntensity in case you missed these.

Yeah, I missed this, thanks for the ping.

I think 3.10 makes the most sense here. For clarification, some aliases documented by #141004 were marked with "soft deprecated" without a formal decision by the C API WG to mark them as such. I did this because:

1. I firmly believe that aliases should be inherently soft-deprecated ("There should be one-- and preferably only one --obvious way to do it").
2. There's not really any to not deprecate an alias, so asking the WG several times would have just been noise and a waste of time.
3. If someone really objected for whatever reason, it's super easy to un-soft-deprecate something.

This means that I bypassed the formal process for soft-deprecation on a few things (sorry!), so, at least for aliases, there's not always a clear version in which something was soft deprecated. For .. soft-deprecated markers, I think it would be best to use the version in which the thing became an alias, or if it started out as an alias (such as PyBUF_WRITEABLE), we should just use the version in which it was added.

OK, we can update it to 3.10 in the backports: #148714, #148715.

And update main in the next PR.

Similarly, this section was added in #141634 and backported to 3.13.

I don't think this was deprecated in code comments. What version should we have?

@ZeroIntensity And what about this one?

These were deprecated via a WG vote, so the formal version for deprecation is 3.15. As Petr said, #141634 wasn't supposed to be backported, but it wasn't worth reverting the 3.14 backport (the 3.13 one failed).