Ezio Melotti added the comment: Thanks for the report and the patch. I think a better way to handle this would be to add a "tag" next to the function name for both deprecations and "new in", and leave the actual deprecation/new-in notes at the bottom, something like: funcname(args) [new in 3.2] [deprecated in 3.5] Func description here. New in 3.2: the funcname() function was added. Deprecated in 3.5: funcname() has been deprecated. Use anotherfunc() instead. I've seen other docs doing it, however I'm not sure how easy it would be to implement something similar for Sphinx (maybe it's necessary to redefine the func/meth/class roles). ---------- nosy: +eric.araujo, ezio.melotti, georg.brandl _______________________________________ Python tracker http://bugs.python.org/issue25467 _______________________________________

Ezio Melotti added the comment:

I’m not sure I understand what you mean by “tag”.

...

funcname(args) [new in 3.2] [deprecated in 3.5] Func description here.

I mean some kind of tag/label next to the name of the function in the documentation (red/orange for deprecations, green for new-in) -- it's not a Sphinx-specific term. I saw it in some other documentation but I can't find it anymore, however if you look at the [task] and [assigned] tags/labels at the top of https://twistedmatrix.com/trac/ticket/5000 you can get a pretty close idea of what I'm thinking about.

Are you saying that the source documentation would remain as-is, but something during the Sphinx _transformation_ would generate the new/deprecated tags?

That's the idea. Ideally the func/meth/class directives [0] would add the tags/labels if they contain version-added/version-changed/deprecated/deprecated-remove directives. [0]: directives look like ".. function:: foo(args)", whereas roles look like :func:`foo`. Functions are defined using directives. In the previous message I mistakenly said "roles". See also https://docs.python.org/devguide/documenting.html#directives ---------- _______________________________________ Python tracker http://bugs.python.org/issue25467 _______________________________________

R. David Murray added the comment: I think Ezio's idea is great. I would not want to see the notices at the top, but a label would make things clear (and the label could be hyperlinked to the note, since sometimes they are a bit of a distance away). Someone has to figure out the Sphinx programming, though. Note that the 'new' label should only appear for stuff that is new in that release. It's not clear to me if it should appear at all in the docs for maintenance releases...that should be discussed. ---------- nosy: +r.david.murray _______________________________________ Python tracker http://bugs.python.org/issue25467 _______________________________________

Tony R. added the comment:

On Oct 26, 2015, at 1:49 PM, Ezio Melotti wrote:

Not sure if there's a clever way to do it though (maybe a CSS class can be added to the directives and the labels can be added with CSS :after).

I was thinking something along these lines. Other possibilities come to mind, also. ---------- _______________________________________ Python tracker http://bugs.python.org/issue25467 _______________________________________

Ezio Melotti added the comment:

I don't want to be distracted by "new in 3.1" tags when reading the 3.6 documentation.

This is true, but on the other hand you might want to see the [new in 3.4] while looking at 3.6 docs and working on a program that must support Python 3.3+. Anyway we can discuss this again once we have a patch -- depending on how it is implemented, it might be easy enough to include the tag only for functions added in the last 2 releases, or perhaps the tag won't be particularly distracting and can be used for all versions. ---------- stage: -> needs patch _______________________________________ Python tracker http://bugs.python.org/issue25467 _______________________________________

Ezio Melotti added the comment: I would rather avoid a JS-based solution. It should be possible to create a mixin that adds the checks for deprecated/versionadded directives among the children of the node, and then define new directives for functions/methods/classes that inherit from the existing one and the mixin. These directives can be added to https://hg.python.org/cpython/file/tip/Doc/tools/extensions/pyspecific.py ---------- _______________________________________ Python tracker http://bugs.python.org/issue25467 _______________________________________

Change by Georg Brandl : ---------- nosy: -georg.brandl _______________________________________ Python tracker https://bugs.python.org/issue25467 _______________________________________