| msg167670 - (view) |
Author: Sarbjit singh (Sarbjit.singh) |
Date: 2012-08-08 06:34 |
| 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) |
|
|
| msg167688 - (view) |
Author: Daniel Ellis (Daniel.Ellis) |
Date: 2012-08-08 12:38 |
| I have been working with ElementTree for the last few months and would love to help out with this. |
|
|
| msg167691 - (view) |
Author: Ezio Melotti (ezio.melotti) *  |
Date: 2012-08-08 16:07 |
| 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. |
|
|
| msg167692 - (view) |
Author: Daniel Ellis (Daniel.Ellis) |
Date: 2012-08-08 16:33 |
| 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> > _______________________________________ > |
|
|
| msg167693 - (view) |
Author: Ezio Melotti (ezio.melotti) * |
Date: 2012-08-08 16:36 |
| 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. |
|
|
| msg167700 - (view) |
Author: Eli Bendersky (eli.bendersky) * |
Date: 2012-08-08 17:51 |
| 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. |
|
|
| msg167710 - (view) |
Author: Daniel Ellis (Daniel.Ellis) |
Date: 2012-08-08 20:26 |
| 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. |
|
|
| msg167766 - (view) |
Author: Eli Bendersky (eli.bendersky) * |
Date: 2012-08-09 07:45 |
| 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). |
|
|
| msg167767 - (view) |
Author: Eli Bendersky (eli.bendersky) * |
Date: 2012-08-09 07:47 |
| 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? |
|
|
| msg167770 - (view) |
Author: Eli Bendersky (eli.bendersky) * |
Date: 2012-08-09 08:11 |
| 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. |
|
|
| msg167785 - (view) |
Author: Daniel Ellis (Daniel.Ellis) |
Date: 2012-08-09 13:41 |
| Changes to documentation per Ezio and Eli's suggestions. |
|
|
| msg167786 - (view) |
Author: R. David Murray (r.david.murray) * |
Date: 2012-08-09 14:20 |
| 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 :) |
|
|
| msg167787 - (view) |
Author: Daniel Ellis (Daniel.Ellis) |
Date: 2012-08-09 14:43 |
| 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. |
|
|
| msg168122 - (view) |
Author: Daniel Ellis (Daniel.Ellis) |
Date: 2012-08-13 16:00 |
| I've updated 2.7 with the examples and made changes where backward compatibility was an issue. |
|
|
| msg168123 - (view) |
Author: Daniel Ellis (Daniel.Ellis) |
Date: 2012-08-13 16:01 |
| Fixed typo I made in examples in default branch. |
|
|
| msg168172 - (view) |
Author: Roundup Robot (python-dev)  |
Date: 2012-08-14 04:21 |
| 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 |
|
|
| msg168173 - (view) |
Author: Eli Bendersky (eli.bendersky) * |
Date: 2012-08-14 04:30 |
| 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? |
|
|
| msg168198 - (view) |
Author: Daniel Ellis (Daniel.Ellis) |
Date: 2012-08-14 13:12 |
| 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. |
|
|
| msg168255 - (view) |
Author: Éric Araujo (eric.araujo) * |
Date: 2012-08-15 02:01 |
| I noticed a long-standing typo in the latest commit: the country is named Liechtenstein :) |
|
|
| msg168280 - (view) |
Author: Roundup Robot (python-dev) |
Date: 2012-08-15 11:27 |
| 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 |
|
|
| msg168281 - (view) |
Author: Eli Bendersky (eli.bendersky) * |
Date: 2012-08-15 11:38 |
| 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 ;) |
|
|
| msg168383 - (view) |
Author: Daniel Ellis (Daniel.Ellis) |
Date: 2012-08-16 15:29 |
| 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). |
|
|
| msg168491 - (view) |
Author: Roundup Robot (python-dev) |
Date: 2012-08-18 02:41 |
| 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 |
|
|
| msg168492 - (view) |
Author: Roundup Robot (python-dev) |
Date: 2012-08-18 02:43 |
| New changeset 7012f6a74f66 by Eli Bendersky in branch 'default': Issue #15586: fix prompts in some documentation examples http://hg.python.org/cpython/rev/7012f6a74f66 |
|
|