[Doc-SIG] DocBook formatter for pythondoc

[Konrad Hinsen]

I have put a first version of a DocBook formatter for pythondoc 0.6 on
my ftp site (ftp://dirac.cnrs-orleans.fr/pub/DocBookFormatter.py). It
doesn't yet support all possible markup, and probably never will,
because pythondoc is much too layout-oriented for DocBook. For
example, it is impossible to have just a "title" in DocBook, titles
are always associated with structural units (chapters, sections,
etc.). Nevertheless, the DocBook formatter is quite useful when used
on appropriate doc strings.

The goal of my formatter is to produce reference chapters for end user
documentation. Therefore I have introduced an option that I think
would be useful for other formatters as well: when you specify the
Option "DocBook_undocumented=0", no documentation will be generated
for items that have no doc string. I use this to exclude methods like
__add__ from end user documentation; instead I mention in the doc
string of the class that the class supports addition.

If you look at the code, you will notice two methods that are
commented out and replaced with different ones. These are the methods
that generate function and method documentation. The original (now
commented) versions produce the "proper" markup according to the
DocBook reference, but unfortunately the existing DocBook stylesheets
were made with C in mind and produce C syntax for every function call!
I hope this will change in later versions, but until then I prefer to
use less specific markup that produces Python syntax.
-- 
-------------------------------------------------------------------------------
Konrad Hinsen                            | E-Mail: hinsen@cnrs-orleans.fr
Centre de Biophysique Moleculaire (CNRS) | Tel.: +33-2.38.25.55.69
Rue Charles Sadron                       | Fax:  +33-2.38.63.15.17
45071 Orleans Cedex 2                    | Deutsch/Esperanto/English/
France                                   | Nederlands/Francais
-------------------------------------------------------------------------------