Naive idiom questions

[Stargaming]

On Thu, 31 Jan 2008 15:30:09 -0600, Terran Melconian wrote:
> * Is there a way to get headings in docstrings?
> 
>     I want to create my own sections, like "OVERVIEW", "EXAMPLES",
>     "AUTHORS", "BUGS", etc.  I can't figure out any way to do this.  In
>     perldoc, I can easily use =head1, but I can't figure out the Python
>     equivalent.  At first I thought I could use (re)structuredtext, but
>     then it became apparent that pydoc(1) does not parse any of this
>     markup.  Am I missing something, or is it just not possible to
>     achieve this effect other than by writing separate, independent
>     manpages?

I could imagine several solutions.

Do it like normal manpages, just use indentation::

    OVERVIEW
        So this is my script.
    
    AUTHORS
        Written by me. :-)

Use ReStructuredText -- it's readable even if it is not parsed by pydoc::

    Overview
    ========
    
    So this is my script.
    
    
    Authors
    =======
    
    Written by me.

Despite being readable even without transformations, you can use 
additional third-party packages to get nice and shiny documentation (HTML 
for most purposes). My favorite is Epydoc_, even though there are a whole 
lot of others (for example the tool used for the CPython docs, Sphinx, or 
just plain docutils_).

.. Epydoc: http://epydoc.sourceforge.net/
.. _docutils: http://docutils.sourceforge.net/

And, uh, if you abandon pydoc and roll your own docstring parser, you 
could basically use *any* markup you like. ``<h1>Overview</h1>``, for 
example.

HTH,