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>Looks like the first line contains a short description (should not exceed one line, as described in <a href="https://www.python.org/dev/peps/pep-0257/#multi-line-docstrings" rel="nofollow">PEP 257</a>), 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.</p>

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

<pre><code>"""A short description

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

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

    Some more explanations.
    """
    pass
</code></pre>

<p>(note that the doc string can be elsewhere, like in a <code>__doc__</code> attribute, as stated <a href="https://docs.python.org/3/library/pydoc.html" rel="nofollow">here</a>)</p>

<p>then <code>pydoc3.4 just_to_see/__init__.py</code> will output:</p>

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

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

<p>Not sure about how to trigger an EXAMPLES section. Couldn't find any example of an EXAMPLE section in the <code>pydoc</code> 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?</p>

python pydoc