Add a new Sphinx soft-deprecated directive#148630
Add a new Sphinx soft-deprecated directive#148630hugovk wants to merge 7 commits intopython:mainfrom
soft-deprecated directive#148630Conversation
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).
| 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.
Co-authored-by: Stan Ulbrych <stan@python.org>
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/