classification
Title: Clearer documentation for cElementTree
Type: enhancement Stage: resolved
Components: Documentation Versions: Python 3.2, Python 3.3, Python 2.7
process
Status: closed Resolution: wont fix
Dependencies: Superseder:
Assigned To: docs@python Nosy List: docs@python, eli.bendersky, eric.araujo, ezio.melotti, fdrake
Priority: normal Keywords: patch

Created on 2012-02-14 15:26 by eric.araujo, last changed 2013-05-20 13:21 by eli.bendersky. This issue is now closed.

Files
File name Uploaded Description Edit
doc-cET.diff eric.araujo, 2012-02-14 15:27
issue14009.doc_cET.1.patch eli.bendersky, 2012-02-16 03:48
Messages (12)
msg153338 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2012-02-14 15:26
This patch should clarify how to use cElementTree usage, as well as improving indexing.
msg153454 - (view) Author: Eli Bendersky (eli.bendersky) * (Python committer) Date: 2012-02-16 03:48
É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
msg153455 - (view) Author: Eli Bendersky (eli.bendersky) * (Python committer) Date: 2012-02-16 03:50
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
msg153456 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2012-02-16 03:55
+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.
msg153457 - (view) Author: Eli Bendersky (eli.bendersky) * (Python committer) Date: 2012-02-16 03:59
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.
msg153557 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2012-02-17 16:06
> 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.”
msg153589 - (view) Author: Eli Bendersky (eli.bendersky) * (Python committer) Date: 2012-02-17 18:37
> > 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 :)
msg153598 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2012-02-17 20:50
> 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.)
msg153599 - (view) Author: Fred Drake (fdrake) (Python committer) Date: 2012-02-17 21:02
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.
msg155997 - (view) Author: Eli Bendersky (eli.bendersky) * (Python committer) Date: 2012-03-16 06:28
É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.
msg156030 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2012-03-16 14:05
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 :)
msg189661 - (view) Author: Eli Bendersky (eli.bendersky) * (Python committer) Date: 2013-05-20 13:21
The ET docs have been significantly revamped in 3.3

I don't think cET needs to be documented. It's just confusing.
History
Date User Action Args
2013-05-20 13:21:26eli.benderskysetstatus: open -> closed
resolution: wont fix
messages: + msg189661

stage: commit review -> resolved
2012-04-29 02:08:17ezio.melottisettype: enhancement
2012-03-16 14:05:18eric.araujosetmessages: + msg156030
versions: + Python 3.3
2012-03-16 06:28:01eli.benderskysetmessages: + msg155997
2012-02-17 21:02:33fdrakesetnosy: + fdrake
messages: + msg153599
2012-02-17 20:50:31ezio.melottisetnosy: + ezio.melotti
messages: + msg153598
2012-02-17 18:37:29eli.benderskysetmessages: + msg153589
2012-02-17 16:06:29eric.araujosetmessages: + msg153557
2012-02-16 03:59:52eli.benderskysetmessages: + msg153457
2012-02-16 03:55:36eric.araujosetmessages: + msg153456
2012-02-16 03:50:45eli.benderskysetmessages: + msg153455
2012-02-16 03:48:45eli.benderskysetfiles: + issue14009.doc_cET.1.patch

messages: + msg153454
2012-02-14 15:27:43eric.araujosetfiles: + doc-cET.diff
keywords: + patch
2012-02-14 15:26:42eric.araujocreate