[issue25467] Put “deprecated” warnings first
New submission from Tony R.: Python has wonderful, detailed documentation. I love it! Unfortunately, I have often found myself reading the otherwise-excellent documentation on a class/function/whatever, only to find out at the END of my reading that it is deprecated. This is frustrating, and counter-intuitive. If something is deprecated, I want to know it before I read any further. I have attached a patch with the relevant changes. I hope it helps! ---------- assignee: docs@python components: Documentation files: 0001-Move-deprecated-blocks-to-the-beginning-of-their-doc.patch keywords: patch messages: 253391 nosy: Tony R., docs@python priority: normal severity: normal status: open title: Put “deprecated” warnings first type: enhancement Added file: http://bugs.python.org/file40851/0001-Move-deprecated-blocks-to-the-beginnin... _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue25467> _______________________________________
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 <report@bugs.python.org> <http://bugs.python.org/issue25467> _______________________________________
Tony R. added the comment:
Thanks for the report and the patch.
Thank you for the review!
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’m not sure I understand what you mean by “tag”. (ASIDE: I’m only marginally familiar with Sphinx, so I don’t know if “tag” has a specific meaning here. I dabble across lots of markup-to-full-docs generation tools; Sphinx is just one that I happen to know the least.) Are you saying that the source documentation would remain as-is, but something during the Sphinx _transformation_ would generate the new/deprecated tags? As long as those tags are clearly visible at-or-near the start, then I’m all for it. If that is what you propose, then I can think of several possible ways to structure the generated HTML & CSS—and from there I would just need to dive into the Sphinx transformations and figure out where to sprinkle the “tags”. ---------- _______________________________________ Python tracker <report@bugs.python.org> <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 <report@bugs.python.org> <http://bugs.python.org/issue25467> _______________________________________
Changes by Brett Cannon <brett@python.org>: ---------- nosy: +brett.cannon _______________________________________ Python tracker <report@bugs.python.org> <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 <report@bugs.python.org> <http://bugs.python.org/issue25467> _______________________________________
Ezio Melotti added the comment:
Note that the 'new' label should only appear for stuff that is new in that release.
This is not a problem if it says [new in x.y] explicitly. This way for each version-added/version-changed/deprecated/deprecated-remove directive we will also have a label. As for the implementation, I'm pretty sure it can be done by changing/redefining all the function/method/class directives. The directives should then be able to inspect the nodes they contain and see if there are any of the aforementioned directives and turn them into labels. 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). ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue25467> _______________________________________
Tony R. added the comment:
On Oct 26, 2015, at 1:49 PM, Ezio Melotti <report@bugs.python.org> 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 <report@bugs.python.org> <http://bugs.python.org/issue25467> _______________________________________
R. David Murray added the comment: Insert "in my opinion" into that sentence. I don't want to be distracted by "new in 3.1" tags when reading the 3.6 documentation. It isn't new from my POV :) ---------- _______________________________________ Python tracker <report@bugs.python.org> <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 <report@bugs.python.org> <http://bugs.python.org/issue25467> _______________________________________
Tony R. added the comment:
On Oct 26, 2015, at 4:28 PM, Ezio Melotti <report@bugs.python.org> wrote:
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.
Smart use of CSS and a sprinkle of JavaScript could solve this. - Add all versions in the markup - By default, use CSS to hide all except latest version - Using JavaScript and a simple `localStorage` variable, save a preference to “lower the version threshold” if desired I tend to prefer non-JS solutions when possible, but this would only take a few lines of code. (And of course, one `localStorage` variable along the lines of `minimumAddedInPythonVersion = ‘3.2’`, or whatever.) —Tony ---------- _______________________________________ Python tracker <report@bugs.python.org> <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 <report@bugs.python.org> <http://bugs.python.org/issue25467> _______________________________________
Change by Brett Cannon <brett@python.org>: ---------- nosy: -brett.cannon _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue25467> _______________________________________
Change by Georg Brandl <georg@python.org>: ---------- nosy: -georg.brandl _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue25467> _______________________________________
participants (5)
-
Brett Cannon -
Ezio Melotti
-
Georg Brandl
-
R. David Murray
-
Tony R.