pkgutil lacks documentation for useful functions

[englabenny]

BPO	7303
Nosy	@birkenfeld, @pjeby, @merwok
Files	pkgutil-docs-py3k-branch.patch: pkgutil reST documentation

^{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 2010-10-15.16:36:06.250>
created_at = <Date 2009-11-10.22:12:31.453>
labels = ['easy', 'type-feature', 'docs']
title = 'pkgutil lacks documentation for useful functions'
updated_at = <Date 2010-10-15.16:36:06.249>
user = 'https://bugs.python.org/englabenny'

bugs.python.org fields:

activity = <Date 2010-10-15.16:36:06.249>
actor = 'georg.brandl'
assignee = 'docs@python'
closed = True
closed_date = <Date 2010-10-15.16:36:06.250>
closer = 'georg.brandl'
components = ['Documentation']
creation = <Date 2009-11-10.22:12:31.453>
creator = 'englabenny'
dependencies = []
files = ['18193']
hgrepos = []
issue_num = 7303
keywords = ['patch', 'easy']
message_count = 7.0
messages = ['95132', '109868', '110612', '110614', '110615', '111520', '118798']
nosy_count = 7.0
nosy_names = ['georg.brandl', 'pje', 'eric.araujo', 'englabenny', 'docs@python', 'BreamoreBoy', 'glimberg']
pr_nums = []
priority = 'normal'
resolution = 'accepted'
stage = 'patch review'
status = 'closed'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue7303'
versions = ['Python 3.2']

[englabenny]

The module pkgutil has no documentation of functions added after its
introduction, in the official python documentation collection.

http://docs.python.org/dev/py3k/library/pkgutil.html

The module is well documented with docstrings.

I assume the module's exposed functions, some very useful, are open for
public use, for example pkgutil.iter_modules and .walk_packages.

Is all that is required copying the docstrings into the documentation?
If someone believes only Python insight and knowledge of reST sytax is
enough to make some passable documentation from the existing docstrings,
I could submit a patch for that.

[BreamoreBoy]

Ulrik could you please submit a patch?

[merwok]

Thanks for your help proposal Ulrik. If I understand the documentation correctly, docstrings should contain enough usage information but not too much. In pkgutil, some examples and long explanations could be removed after you move them to the reST doc.

Make sure to work from a checkout of 3.2 (branch named py3k) to have the latest updates. This page contains some tips about patches: http://www.python.org/dev/patches/

You can ask any questions here or on the docs@python.org mailing list. Thanks again.

[merwok]

Other useful advice:
http://docs.pythonsprints.com/core_development/beginners#building-the-documentation
http://docs.python.org/documenting/

[merwok]

Wrong link, sorry everyone for the noise:
http://docs.pythonsprints.com/core_development/beginners.html#building-the-documentation

[glimberg]

I've taken the liberty of creating a patch for this issue. I've taken the docstrings fromt he pkgutil module and conveted them to reST.

Please let me know if there are any changes necessary.

[birkenfeld]

Fixed markup a bit and committed in r85538. Thanks!