how to document a python package

Question

I know what's the standard way to document functions, classes and modules, but how do I document packages - do I put a docstring in __init__.py, or something else?

Answer 1

Yes, just like for a function or class comment, the first item in the init.py file should be a comment string:

"""
This is the xyz package.
"""

Now if you import the package, and use help(package), you will see your docstring. See more here: http://www.python.org/dev/peps/pep-0257/

Answer 2

See PEP257

A package may be documented in the module docstring of the __ init __.py file in the package directory.

Answer 3

Documenting is a good idea, so long as you don't document something obvious in your code

Try to understand that most people reading your source will understand python, so commenting or documenting lines like this is pointless:

a = 1     #this assigns 1 to a

But commenting or documenting a rather complicated function or class is a good idea.

General rule of thumb: Imagine the next person to work on your code is a Axe wielding maniac and they know where you live.

That way you will always leave "helpful" comments/doc's