sdruser sdruser - 2 months ago 14
Python Question

Python pydoc for python packages

I'm trying to document a python package in init.py and it's unclear to me how pydoc parses a """triple bracketed""" comment to display to the user via:

>>> help(package)


or

$ pydoc package


How is the comment parsed to provide content in the NAME and DESCRIPTION sections of the pydoc output? Are there other sections I can populate as well such as EXAMPLES?

Answer

Let's consider this dummy package:

./whatever
├── __init__.py
├── nothing
│   └── __init__.py
└── something.py

in ./whatever/__init__.py we have:

"""
This is whatever help info.

This is whatever description

EXAMPLES:
    ...
"""

__version__ = '1.0'

variable = 'variable'

Now running python shell:

➜  ~ python
Python 2.7.12 (default, Jul  1 2016, 15:12:24) 
[GCC 5.4.0 20160609] on linux2
Type "help", "copyright", "credits" or "license" for more information.
>>> import whatever
>>> help(whatever)

output is:

NAME
    whatever - This is whatever help info.

FILE
    /home/el/whatever/__init__.py

DESCRIPTION
    This is whatever description

    EXAMPLES:
        ...

PACKAGE CONTENTS
    nothing (package)
    something

DATA
    __version__ = '1.0'
    variable = 'variable'

VERSION
    1.0

Examples you can provide in description section. So in ./whatever/__init__.py.

Hope that helps.

Comments