Python pydoc for python packages
<p>I'm trying to document a python package in <strong>init.py</strong> and it's unclear to me how pydoc parses a """triple bracketed""" comment to display to the user via:</p>

<pre><code>&gt;&gt;&gt; help(package)
</code></pre>

<p>or </p>

<pre><code>$ pydoc package  
</code></pre>

<p>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?</p>

<p>Let's consider this dummy package:</p>

<pre><code>./whatever
âââ __init__.py
âââ nothing
âÂ Â  âââ __init__.py
âââ something.py
</code></pre>

<p>in <code>./whatever/__init__.py</code> we have:</p>

<pre><code>"""
This is whatever help info.

This is whatever description

EXAMPLES:
    ...
"""

__version__ = '1.0'

variable = 'variable'
</code></pre>

<p>Now running python shell:</p>

<pre><code>â  ~ 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.
&gt;&gt;&gt; import whatever
&gt;&gt;&gt; help(whatever)
</code></pre>

<p>output is:</p>

<pre><code>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
</code></pre>

<p>Examples you can provide in description section. So in <code>./whatever/__init__.py</code>. </p>

<p>Hope that helps.</p>

python pydoc