Feature: support ..deprecated Sphinx directive
NicolasHug opened this issue · comments
Same as pytorch/pytorch#73007
The .. deprecated :: sphinx directive isn't visible enough in the rendered docs:
.. deprecated:: 0.12
This is deprecated, use blah instead
will simply render as:
Could we make it more obvious, similar to .. note:: or .. warning:: ? These are much more visible:
Is this issue solved yet? If not, I may help.
My thought is to add a new admonition directive item https://docutils.sourceforge.io/docs/ref/rst/directives.html
in our theme to overwrite the directive definition in sphinx:
https://github.com/sphinx-doc/sphinx/blob/13fb17468e547b18b3b8d6b5616ef3d1eb23ac98/sphinx/domains/changeset.py#L147
But I'm not clear what is the expected looking for the new deprecation admonition.
I started, but haven't published anything yet. I can take that up in roughly a month. If you want it earlier, be aware that the deprecated directive is not an admonition. Took me quite some time to figure that out.
Right, I think the sphinx deprecated directive definition is in the previous link I shared, which is not an admonition but a simple directive.
I can solve this issue in recent days, but need to know what's the expected behavior from maintainers.
Thanks for your interest in this issue @ain-soph. I think that making it look like a .. warning (replacing "WARNING" with "DEPRECATION") would be a good start.
We can bike-shed on the color afterward :)
@NicolasHug Then the admonition should be .. deprecated or .. deprecation since the text is DEPRECATION?
I'm hoping that the text of the headline is independent of the name of the directive?
It should still be .. deprecated, since it's a sphinx built-in directive. The key here is to change how it renders with the pytorch-sphinx-theme.
Got it. That makes sense. I'll get the example soon.
@NicolasHug
I first tested at my own theme repo.
The commit is ain-soph/trojanzoo_sphinx_theme@e8444f8
The generated docs is https://ain-soph.github.io/trojanzoo_sphinx_theme/demo/demo.html#admonitions
The example figure is 
According to the internal chat with @NicolasHug , we don't want a new admonition any longer.
Instead, we just want to modify the current looking to keep it similar as behaved in sklearn
The current looking after the new PR:
Since we also use this theme in TorchGeo, @ain-soph asked me to share my opinion on this discussion.
In terms of syntax, we definitely want to stick with the builtin directive:
.. deprecated:: 3.1
Use :func:`spam` instead.We don't want to create our own custom admonition for this. This is important if, e.g., we want to switch to a new theme someday. We want to make sure we use a directive that all themes support so as to avoid straying further from other themes. We use this same directive in TorchGeo already.
In terms of appearance, I do have a slight preference for the appearance of warning. If we can keep the same rST syntax but use an appearance similar to warning that would be ideal to me. We should still include the version in which the feature is deprecated, and maybe a way to document when the feature is planned for removal?
@adamjstewart I completely agree with you that it should NOT raise any concern during switching themes. We should definitely avoid the articulation cost.
For the appearance, what's your expected looking?
.. deprecated:: 3.0
This is deprecated since 3.0
Is it something like this?
If so, I'm afraid that we still need to create a new custom admonition. But for theme users, they should feel no difference when coding the documents.
If we stick to the sphinx deprecated directive that is actually a changeset, the only thing we can do is quite limited (just like sklearn does): add a colorful bbox in css.
Thanks a lot @ain-soph , the renderring in #156 (comment) looks infinitely better than what we currently have, so LGTM. We can always improve / change how it looks later if we feel like it.