Add a new Sphinx soft-deprecated directive#148630
Add a new Sphinx soft-deprecated directive#148630hugovk wants to merge 9 commits intopython:mainfrom
soft-deprecated directive#148630Conversation
hugovk
requested review from
AA-Turner,
ZeroIntensity and
ericsnowcurrently
as code owners
StanFromIreland
left a comment
StanFromIreland
left a comment
There was a problem hiding this comment.
This is great Hugo, I also had been dreaming of this recently!
| """ | ||
|
|
||
| def run(self) -> list[Node]: | ||
| versionlabels[self.name] = sphinx_gettext( |
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
How will this work in a translation,
_add_glossary_linksetsmarker = "Soft deprecated"?
I just pushed bee4f6c, I think that might do it?
Also, you'll have to add the message to
dummy.htmlfor it to be extracted IIRC.
Thanks, added.
There was a problem hiding this comment.
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).
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
Yes, but how are translators supposed to know that?
There was a problem hiding this comment.
Shall we add a comment in Doc/tools/templates/dummy.html?
There was a problem hiding this comment.
Translators won't see it unfortunately, Sphinx doesn’t support adding comments for translators. Can we have :term:`soft deprecated` in the string?
| versionlabel_classes[self.name] = "" | ||
|
|
||
| for node in result: | ||
| # Add "versionchanged" class so existing theme CSS applies |
There was a problem hiding this comment.
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?
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
I like Bénédikt's purple (rgb(175, 0, 255) below) suggestion, but blue is alright:
There was a problem hiding this comment.
I'm not so keen on purple, and the contrast ratio is too low for dark mode:
There was a problem hiding this comment.
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).
There was a problem hiding this comment.
Yeah, we can use different colours for light and dark. Anyway, we can bikeshed that in the theme.
Co-authored-by: Stan Ulbrych <stan@python.org>
|
Would you mind also updating C API entries that only reference For example:
I'm also happy to do this in a follow-up if you'd rather land this PR sooner. |
|
@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. |
| Soft-deprecated aliases | ||
| ^^^^^^^^^^^^^^^^^^^^^^^ |
There was a problem hiding this comment.
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-alisesjust above it - Add to
Doc/tools/removed-ids.txt - Revert
There was a problem hiding this comment.
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.
4 participants
Follow on from #86519 and #148100.
Add a new Sphinx
soft-deprecateddirective, 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/