CODEWITHSUNDEEP
pythonpydoc
sdruser
sdruser

Reputation: 46

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?

Upvotes: 1

Views: 1795

Answers (2)

zezollo
zezollo

Reputation: 5017

Looks like the first line contains a short description (should not exceed one line, as described in PEP 257), that will be put after the name; followed by a blank line and then a paragraph, what will be used to provide content in the DESCRIPTION section.

So, for instance if you have this in just_to_see/__init__.py (simple example with a module):

"""A short description

A longer description on several lines etc.
blablabla etc."""

def a_function():
    """
    An interesting introductive comment.

    Some more explanations.
    """
    pass

(note that the doc string can be elsewhere, like in a __doc__ attribute, as stated here)

then pydoc3.4 just_to_see/__init__.py will output:

Help on module __init__:

NAME
    __init__ - A short description

DESCRIPTION
    A longer description on several lines etc.
    blablabla etc.

FUNCTIONS
    a_function()
        An interesting introductive comment.

        Some more explanations.

FILE
    /home/nico/temp/just_to_see/__init__.py

If your package is installed (in a virtual environment for instance), some more informations can be found by pydoc from its setup.py (like author's name etc.).

Not sure about how to trigger an EXAMPLES section. Couldn't find any example of an EXAMPLE section in the pydoc output of a standard python library yet (but I haven't browsed them all). Maybe you can add such a section in the long description in the doc string of your package. But as they don't seem to do it in the standard libraries, maybe it's not the right place to put examples?

Upvotes: 1

turkus
turkus

Reputation: 4893

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.

Upvotes: 2

Related Questions