[issue14009] Clearer documentation for cElementTree
New submission from Éric Araujo <merwok@netwok.org>: This patch should clarify how to use cElementTree usage, as well as improving indexing. ---------- assignee: docs@python components: Documentation messages: 153338 nosy: docs@python, eli.bendersky, eric.araujo priority: normal severity: normal stage: commit review status: open title: Clearer documentation for cElementTree versions: Python 2.7, Python 3.2 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue14009> _______________________________________
Changes by Éric Araujo <merwok@netwok.org>: ---------- keywords: +patch Added file: http://bugs.python.org/file24519/doc-cET.diff _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue14009> _______________________________________
Eli Bendersky <eliben@gmail.com> added the comment: Éric, indeed it clarifies the usage, but my concern is that it also moves the first mention of the module further down. There's no real reason for someone using CPython 2.7 or 3.2 *not* to use cET. So, some mention should appear in the opening paragraph. I'm attaching a patch that shows one possibility (based on your patch). It was generated vs. branch 2.7 ---------- Added file: http://bugs.python.org/file24527/issue14009.doc_cET.1.patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue14009> _______________________________________
Eli Bendersky <eliben@gmail.com> added the comment: Also, I must add that I absolutely hate the opening paragraph of the documentation in this module. Once 14006 is implemented, parts of it should be backported to 2.7 and 3.2 That would be an orthogonal change to what we're discussion here, though ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue14009> _______________________________________
Éric Araujo <merwok@netwok.org> added the comment: +1. Barring other feedback, I will commit your patch.
Also, I must add that I absolutely hate the opening paragraph of the documentation in this module.
This: The :class:`Element` type is a flexible container object, designed to store hierarchical data structures in memory. The type can be described as a cross between a list and a dictionary. ? Yeah, it’s not quite good. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue14009> _______________________________________
Eli Bendersky <eliben@gmail.com> added the comment: If you want to collect additional feedback, you may want to add some other people to the Nosy list :-) Alternatively, since it's a small doc change you can just commit it and it can be fixed later if someone strongly objects.
This:
The :class:`Element` type is a flexible container object, designed to store hierarchical data structures in memory. The type can be described as a cross between a list and a dictionary. ? Yeah, it’s not quite good.
Yes. You read the first section of a module's doc and you have *no idea* what the module is and how to use it. I plant to work on this for 3.3 in the context of issue 14006. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue14009> _______________________________________
Éric Araujo <merwok@netwok.org> added the comment:
If you want to collect additional feedback, you may want to add some other people to the Nosy list :-) I did not want more feedback, I wanted to leave time for interested parties to find this bug for themselves and eventually comment :)
One question: when I merge the new doc from 3.2 to 3.3, do I remove the new section, as the cET module is now deprecated? If I do that we’d lose the indexing (i.e. without a module directive there will be no entry in the module index not the alphabetical index). I could leave the cET section so that we get the indexing but change the text to “Deprecated alias of ET.” ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue14009> _______________________________________
Eli Bendersky <eliben@gmail.com> added the comment:
If you want to collect additional feedback, you may want to add some other people to the Nosy list :-) I did not want more feedback, I wanted to leave time for interested parties to find this bug for themselves and eventually comment :)
One question: when I merge the new doc from 3.2 to 3.3, do I remove the new section, as the cET module is now deprecated? If I do that we’d lose the indexing (i.e. without a module directive there will be no entry in the module index not the alphabetical index). I could leave the cET section so that we get the indexing but change the text to “Deprecated alias of ET.”
I don't see a need for cElementTree to be indexed in the doc of 3.3 Assuming a new Python user who starts with 3.3, he should not even know about the existence of cElementTree (bar a small notice that says it's deprecated, which will be of no interest to him). The cElementTree module stays in its place in 3.3, but that's only for backwards compatibility. Officially, it doesn't exist :) ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue14009> _______________________________________
Ezio Melotti <ezio.melotti@gmail.com> added the comment:
Officially, it doesn't exist :)
Keep in mind that many users will find about it from the Internet, and it's better to clearly say what it is and that it shouldn't be used anymore than pretending it doesn't exist. (AFAIU this is the current situation, since there is a warning, but leaving it indexed wouldn't hurt IMHO.) ---------- nosy: +ezio.melotti _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue14009> _______________________________________
Fred L. Drake, Jr. <fred@fdrake.net> added the comment: Developers with existing code can reasonably be expected to look it up based on what they're currently importing, so an entry that points to the new recommended practice is good. ---------- nosy: +fdrake _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue14009> _______________________________________
Eli Bendersky <eliben@gmail.com> added the comment: Éric, what stops us from closing this issue? Given Ezio and Fred's feedback, I don't object to indexing cET in 3.3 - I guess it can't hurt. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue14009> _______________________________________
Éric Araujo <merwok@netwok.org> added the comment: I will commit the patch, keeping the indexing in 3.3 as agreed. I just moved to a new city, so today is paperwork day but in the evening or tomorrow I’ll do Python work :) ---------- versions: +Python 3.3 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue14009> _______________________________________
Changes by Ezio Melotti <ezio.melotti@gmail.com>: ---------- type: -> enhancement _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue14009> _______________________________________
Eli Bendersky added the comment: The ET docs have been significantly revamped in 3.3 I don't think cET needs to be documented. It's just confusing. ---------- resolution: -> wont fix stage: commit review -> committed/rejected status: open -> closed _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue14009> _______________________________________
participants (4)
-
Eli Bendersky -
Ezio Melotti
-
Fred L. Drake, Jr.
-
Éric Araujo