[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-beginning-of-their-doc.patch ___ Python tracker <http://bugs.python.org/issue25467> ___ ___ Python-bugs-list mailing list Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue25467] Put “deprecated” warnings first
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 <http://bugs.python.org/issue25467> ___ ___ Python-bugs-list mailing list Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue25467] Put “deprecated” warnings first
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> ___ ___ Python-bugs-list mailing list Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue25467] Put “deprecated” warnings first
Tony R. added the comment: > On Oct 26, 2015, at 4:28 PM, Ezio Melotti 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 <http://bugs.python.org/issue25467> ___ ___ Python-bugs-list mailing list Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue26366] Use “.. versionadded” over “.. versionchanged” where appropriate
New submission from Tony R.: In the documentation, I noticed several uses of ``.. versionchanged::`` that described things which had been added. I love Python, and its documentation, and I wanted to contribute. So, I figured a low-risk contribution would be to change ``.. versionchanged::`` to “.. versionadded” where appropriate. (I also tweaked the descriptions accordingly. E.g., “Added the *x* argument” became “The *x* argument”, because it’s unnecessary to say “added” in a description under “.. versionadded”.) I did also make a few unrelated tweaks along the way--all very minor, and related to phrasing or formatting. Please let me know if I can do anything else to get this merged! -- assignee: docs@python components: Documentation files: _docs-version-markup.patch keywords: patch messages: 260313 nosy: Tony R., docs@python priority: normal severity: normal status: open title: Use “.. versionadded” over “.. versionchanged” where appropriate type: enhancement Added file: http://bugs.python.org/file41929/_docs-version-markup.patch ___ Python tracker <http://bugs.python.org/issue26366> ___ ___ Python-bugs-list mailing list Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue26366] Use “.. versionadded” over “.. versionchanged” where appropriate
Tony R. added the comment: > My weak opinion is that a new parameter is a new API item, not just a change > in behaviour, so should probably have “versionadded”. This was my reasoning as well. Also, when I noticed so many instances of ``.. versionchanged`` that all say “Added the *x* parameter” (or whatever), it strikes me that these are a *large class of changes*, which all have some kind of addition in common. If you think about it, deprecations and removals are also changes, but they are a large-enough class of changes to merit a distinct markup directive. So, just as this is true for “deprecated” or “deprecated-removed”, I believe it is just as true for “added”. Once all additions, deprecations, and removals have been marked up as such, I think find that there’s still PLENTY of annotations that remain under ``.. versionchanged``. Put another way: Since these are all different types of changes, it is most useful to the reader if the most specific *type* of change is reflected in the markup. -- ___ Python tracker <http://bugs.python.org/issue26366> ___ ___ Python-bugs-list mailing list Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue26366] Use “.. versionadded” over “.. versionchanged” where appropriate
Tony R. added the comment: > Here are the original descriptions of the old LaTeX version. Holy crap! You all used to use LaTeX?! :D (I know--LaTeX is still going strong in academia. I just had no idea it was ever part of Python’s documentation, except as an output format.) > Adding a parameter is explicitly a "versionchanged" kind of change. > > Since the Sphinx items are supposed to be equivalent, this has always been > the intention, even if the current devguide deviates. Ah, okay. Well then, if this is the sort of place where the status quo is sacred, then there is nothing more to discuss. But if anyone reading this is open to the idea, please re-read my previous comment in this thread. The quoted LaTeX docs are clear, but I still believe my “all changes = (deprecated-removed changes) + (added changes) + (other changes)” interpretation makes more sense than the LaTeX definition. I also think it is more helpful to the *reader*--which, I respectfully suggest, should be the basis for any documentation’s guidelines--by marking up changes according to this grouping. It’s not my desire to be troublesome by making one more appeal. I simply want to point out that just because somebody wrote the LaTeX definitions a long time ago doesn’t mean that we cannot rewrite them. They were written by somebody just like us, after all. If it’s not obvious by now, I feel strongly about good semantic markup. The purpose of semantic markup is to describe what something *is*. I just think that changes form a hierarchy, with a generic “change” as something of the base class, and “deprecated”, “removed”, and “added” as specializations. If you’re reading this, and you feel similarly--speak up! What do you think? Respectfully, —Tony -- ___ Python tracker <http://bugs.python.org/issue26366> ___ ___ Python-bugs-list mailing list Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue26366] Use “.. versionadded” over “.. versionchanged” where appropriate
Tony R. added the comment: > Part of the problem is getting the granularity right. The initial intent was > that 'version*' were annotations for the enclosing object (function, class, > method, etc.). If we want to have something more granular (parameter > added / deprecated / whatever), we should have distinct markup for that. > > That could look something like: > > .. parameteradded:: alternate 3.6 >Further explanation goes here. > > It's helpful to think of these annotations as pronouns; the antecedent > needs to be clear before they can be interpreted correctly. Isn’t language fun?!?! *insane smile* 8) > It sounds > like that needs to be clarified in the documentation, and possibly > provision added for a more fine-grained form of annotation. Okay. I can participate in the discussion of that, if it would help...but adding a completely new annotation type is outside my current ability to contribute. > > Well then, if this is the sort of place where the status quo is sacred, > > then there is nothing more to discuss. > > That wasn't my intention when quoting the old documenting guide, it was just > to show what the intent was (and still is), and that I didn't just invent it. Your intent was clear to me! I did not mean to say that you -- or anyone -- just invented it. I only know that mature projects (like Python) tend to hold more strongly to the status quo, and that I was advocating a change that was probably going to be an uphill battle to convince others as worthwhile. > That's a nice strawman -- we all feel semantic markup is important, and we > are talking about nothing but semantic markup here. We're just discussing > the interpretation of one aspect of the semantics. It was not my wish to set up a strawman. (I have no formal training in logic, anyways; I’d probably screw it up if I deliberately tried!) The reason I was stressing semantic markup is because I anticipated resistance from the mindset of “Ugh, I don’t want to deal with this tedious crap!” I wanted to emphasize semantic markup as something valuable -- worth making an effort for, even if it might appear tedious or trivial at first glance. That said, I think it’s time for me to bow out of this conversation. I’ve never made a successful contribution to any part of Python, including the documentation. There was some talk of updating the devguide or adding new annotations, so I hope that something good comes out of that! But the issue patch is where my comfort level is right now, and it appears that it’s a no-go. Thank you for your time, your consideration, and the discussion! —Tony -- ___ Python tracker <http://bugs.python.org/issue26366> ___ ___ Python-bugs-list mailing list Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
