Provide examples in Python doc for usage of various modules

[Sarbjitsingh]

BPO	15583
Nosy	@ezio-melotti, @bitdancer

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = None
closed_at = <Date 2012-08-08.05:07:46.841>
created_at = <Date 2012-08-08.04:27:00.817>
labels = ['type-feature', 'docs']
title = 'Provide examples in Python doc for usage of various modules'
updated_at = <Date 2012-08-08.05:07:46.839>
user = 'https://bugs.python.org/Sarbjitsingh'

bugs.python.org fields:

activity = <Date 2012-08-08.05:07:46.839>
actor = 'r.david.murray'
assignee = 'docs@python'
closed = True
closed_date = <Date 2012-08-08.05:07:46.841>
closer = 'r.david.murray'
components = ['Documentation']
creation = <Date 2012-08-08.04:27:00.817>
creator = 'Sarbjit.singh'
dependencies = []
files = []
hgrepos = []
issue_num = 15583
keywords = []
message_count = 3.0
messages = ['167657', '167659', '167661']
nosy_count = 5.0
nosy_names = ['ezio.melotti', 'r.david.murray', 'eli.bendersky', 'docs@python', 'Sarbjit.singh']
pr_nums = []
priority = 'normal'
resolution = None
stage = 'resolved'
status = 'closed'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue15583'
versions = []

[Sarbjitsingh]

For beginners who are learning Python, it would be very helpful if Python doc could provide examples on usage of various methods/attributes of different modules.

For eg: If you look at ElementTree XMl module or take any other standard module, examples which are provided are very limited making it hard for new users to learn those modules and have to search internet for its usage. Providing examples on usage of module attributes/methods will help users to quickly understand it.

[ezio-melotti]

If you look at ElementTree XMl module or take any other
standard module, examples which are provided are very limited

We already try to provide examples where/when appropriate, and several modules have examples showing the basic usage. Often, documenting all the methods will only make the documentation less readable, so only the most important/common functions/methods have examples. Some modules also have separate howtos that contain extensive examples.

If you think some specific module (like ElementTree) needs more examples, feel free to open specific reports.

[bitdancer]

I'm closing this with no specific resolution because the real resolution is "this issue is too general" :)

As Ezio said, specific suggestions are welcome, but should be in separate issues limited to the module/example proposed.