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?
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.
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?
