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,
--
http://mail.python.org/mailman/listinfo/python-list
