Pydoc: adding sections

Question

I would like to improve the documentation of my python module with additional sections.

For example, let's consider this:

$ cat test.py
"""Some module

This stuff goes to the "DESCRIPTION" section.
"""

It will be rendered as follows:

$ pydoc test
Help on module test:

NAME
    test - Some module

DESCRIPTION
    This stuff goes to the "DESCRIPTION" section.

FILE
    /tmp/tmp.XlLL4c82kb/test.py

Is there a way to have a SYNOPSYS section, where I can show some usage examples?

What I would like:

$ pydoc test
Help on module test:

NAME
    test - Some module

SYNOPSYS
    import test
    test.foobar()

DESCRIPTION
    This stuff goes to the "DESCRIPTION" section.

Answer 1

As far as I can tell, the synopsis is only used by the man page output. It looks like it pulls out the top like of docstring or comment and it looks like it tries to respect continuations.

Outside of the source code here, pydoc's ad hoc markup language is poorly documented.