[issue15586] Provide some examples for usage of ElementTree methods/attributes
New submission from Sarbjit singh: Please provide some basic usage examples for ElementTree module documentation. While parsing an xml, most common scenarios will be reading elements from xml, modifying elements, removal of elements. Though there are few examples given for modification of xml element. But if you look from beginners learning point of view, its very hard to just get any idea from the example that is currently provided. There is lot of text there, but what would be more helpful is some small examples for each function so that user can quickly understand its usage there only. I myself is learning Python, but in order to start using this module, i had to search lot of articles on internet on usage of this module. If we could have provided some basic use cases in Python doc itself, user would not have to rely on external sources for learning its usage. Some Basic Scenarios: 1) Parsing an xml and finding some elements of xml 2) deletion of an element from an xml and writing back 3) Modification of an xml element 4) Usage of XPath queries (some basic usage) ---------- assignee: docs@python components: Documentation messages: 167670 nosy: Sarbjit.singh, docs@python, eli.bendersky priority: normal severity: normal status: open title: Provide some examples for usage of ElementTree methods/attributes type: enhancement _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15586> _______________________________________
Changes by Ezio Melotti <ezio.melotti@gmail.com>: ---------- keywords: +easy nosy: +ezio.melotti stage: -> needs patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15586> _______________________________________
Daniel Ellis added the comment: I have been working with ElementTree for the last few months and would love to help out with this. ---------- nosy: +Daniel.Ellis _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15586> _______________________________________
Ezio Melotti added the comment: Daniel, I would suggest you to start with a basic example that gives an idea about how to use the module and its main functionalities. If necessary you could add a section at the bottom with more examples. You can also show how a method works with a short snippet (2-3 lines) just after the documentation of the method, but this doesn't mean that every method should have one. If you have lot of examples you might consider doing a separate tutorial/howto. As a reference see the examples in http://docs.python.org/py3k/library/html.parser.html and http://docs.python.org/py3k/library/unittest.html#basic-example. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15586> _______________________________________
Daniel Ellis added the comment: Thank you Ezio, I will use that as a reference. What is the general workflow for updating documentation across python versions? Should I check to see if the documentation for the module changes across python versions and create patches for each version? Or is it sufficient to create a patch for one version? On Wed, Aug 8, 2012 at 12:07 PM, Ezio Melotti <report@bugs.python.org>wrote:
Ezio Melotti added the comment:
Daniel, I would suggest you to start with a basic example that gives an idea about how to use the module and its main functionalities. If necessary you could add a section at the bottom with more examples. You can also show how a method works with a short snippet (2-3 lines) just after the documentation of the method, but this doesn't mean that every method should have one. If you have lot of examples you might consider doing a separate tutorial/howto.
As a reference see the examples in http://docs.python.org/py3k/library/html.parser.html and http://docs.python.org/py3k/library/unittest.html#basic-example.
----------
_______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15586> _______________________________________
---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15586> _______________________________________
Ezio Melotti added the comment: Usually a patch against "default" (i.e. Python 3) is enough, if there are several differences with Python 2 you might want to provide one for 2.7 too. See also the devguide at http://docs.python.org/devguide/ for more information about the workflow. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15586> _______________________________________
Eli Bendersky added the comment: Please note that the documentation of ET has been significantly improved in 3.3, with added examples, etc. You can start by backporting whatever is relevant to earlier versions (2.7/3.2) - do not add new documentation contents to 2.7/3.2 before the changes from 3.3 are backported, because we can't have divergent docs. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15586> _______________________________________
Daniel Ellis added the comment: I've made a couple more additions/changes to the documentation in the default branch, per Eli's recommendation, since there were already a lot of good examples added. I'd like to also backport this to 2.7 but wanted to make sure these changes were good before moving forward. I just saw Eli's message about doing the backporting before making further changes but had already been working on making these changes. I can go ahead and work on the backport if you feel this patch is too much to do first, but I believe every example I added is backwards compatible. ---------- keywords: +patch Added file: http://bugs.python.org/file26726/default_branch_etree_doc.patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15586> _______________________________________
Changes by Eli Bendersky <eliben@gmail.com>: ---------- versions: +Python 2.7, Python 3.3, Python 3.4 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15586> _______________________________________
Eli Bendersky added the comment: I provided some comments on your patch in the code-review tool. Thanks for the contribution, Daniel. It's fine to first apply these changes to 3.3 and then backport to 2.7 (I don't think 3.2 is necessary because most users use the online docs anyway). ---------- versions: -Python 2.7 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15586> _______________________________________
Changes by Eli Bendersky <eliben@gmail.com>: ---------- versions: +Python 2.7 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15586> _______________________________________
Eli Bendersky added the comment: Sarbjit, if you look at the docs of 3.3, I think most of what you're asking for is there (especially once you count Daniel's commit). What else is missing in your opinion? ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15586> _______________________________________
Eli Bendersky added the comment: Sarbjit: first of all, look at the up-to-date documentation for 3.3 (it's available online at http://docs.python.org/dev/ Then, on a checkout of the 3.3 code (default branch) you can apply Daniel's patch (it's in the "Files" section in this Issue) and look at the updated documentation. MOST IMPORTANTLY: read http://docs.python.org/devguide/index.html thoroughly - it will answer most of your questions. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15586> _______________________________________
Daniel Ellis added the comment: Changes to documentation per Ezio and Eli's suggestions. ---------- Added file: http://bugs.python.org/file26741/default_branch_etree_doc_2.patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15586> _______________________________________
R. David Murray added the comment: My understanding is that we try to keep the documentation of all active branches (2.7, 3.2, and 3.3 currently) in sync except where there are new features/new deprecations in the development version. So if the 2.7 docs are update, I think the 3.2 docs should be too. There will be one more release of 3.2, and the Windows version will bundle the docs, so I think it is worthwhile to do. But I'm not going to do it, so if no one volunteers to do it and apply the patch, that's fine :) ---------- nosy: +r.david.murray _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15586> _______________________________________
Daniel Ellis added the comment: At the moment, the documentation for 2.7 is behind the documentation for 3.3. I will be working on backporting this next, but it will be a little more difficult than simply copying the existing documentation, since some key things in etree changed in the transition to 3.x. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15586> _______________________________________
Daniel Ellis added the comment: I've updated 2.7 with the examples and made changes where backward compatibility was an issue. ---------- Added file: http://bugs.python.org/file26785/2.7_branch_etree_doc.patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15586> _______________________________________
Daniel Ellis added the comment: Fixed typo I made in examples in default branch. ---------- Added file: http://bugs.python.org/file26786/default_branch_etree_doc_3.patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15586> _______________________________________
Roundup Robot added the comment: New changeset fc66730dae4c by Eli Bendersky in branch 'default': Issue #15586: add some examples to ElementTree documentation. Patch by Daniel Ellis. http://hg.python.org/cpython/rev/fc66730dae4c ---------- nosy: +python-dev _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15586> _______________________________________
Eli Bendersky added the comment: I committed your patch to default (3.3) with some minor fixes. Please go over them as you will need to apply them to the 2.7 patch. I've reviewed the 2.7 patch as well - it's an initial review. Did you execute all the code samples on 2.7? ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15586> _______________________________________
Daniel Ellis added the comment: Thank you for the review Eli. I've made your changes and attached the updated patch. I did run all of the code snippets that are being added on 2.7, and the only thing I found different was the changed print statement. I don't believe I overlooked anything, but I may have made a mistake. ---------- Added file: http://bugs.python.org/file26802/2.7_branch_etree_doc_2.patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15586> _______________________________________
Éric Araujo added the comment: I noticed a long-standing typo in the latest commit: the country is named Liechtenstein :) ---------- nosy: +eric.araujo _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15586> _______________________________________
Roundup Robot added the comment: New changeset 8d90fde35cc6 by Eli Bendersky in branch 'default': Issue #15586: typo fix. This commit is accompanied by an apology for all Liechtensteiners out there, and a thanks to Eric Araujo for noticing. http://hg.python.org/cpython/rev/8d90fde35cc6 ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15586> _______________________________________
Eli Bendersky added the comment: Daniel, this looks good except that the section numbering is different from 3.3 where the object/function reference sections were nested under "Reference". Could you fix your patch to align the 2.7 doc to this structure? P.S. Éric's comment also has to be fixed ;) ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15586> _______________________________________
Daniel Ellis added the comment: Made changes in structure in 2.7 branch to match 3.3 based on Eli's comments. Updated input prompt in examples per Ezio's review (though the default branch will still need this update). ---------- Added file: http://bugs.python.org/file26853/2.7_branch_etree_doc_3.patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15586> _______________________________________
Roundup Robot added the comment: New changeset 094423a65a4e by Eli Bendersky in branch '2.7': Issue #15586: porting ET's new documentation bits to 2.7. Patch by Daniel Ellis http://hg.python.org/cpython/rev/094423a65a4e ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15586> _______________________________________
Roundup Robot added the comment: New changeset 7012f6a74f66 by Eli Bendersky in branch 'default': Issue #15586: fix prompts in some documentation examples http://hg.python.org/cpython/rev/7012f6a74f66 ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15586> _______________________________________
Changes by Eli Bendersky <eliben@gmail.com>: ---------- resolution: -> fixed stage: needs patch -> committed/rejected status: open -> closed _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue15586> _______________________________________
participants (7)
-
Daniel Ellis -
Eli Bendersky
-
Ezio Melotti
-
R. David Murray
-
Roundup Robot
-
Sarbjit singh
-
Éric Araujo