This is the mail archive of the davenport@berkshire.net mailing list for the Davenport project.


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]

DAVENPORT: DocBook for documenting Python code


A while ago I became interested in DocBook for preparing the manual of
a rather large Python library. However, I soon found out that all the
markup for code documentation is meant for C, and whenever I convert
my manual to HTML using Norman Walsh's stylesheets I automatically get
C syntax.

So how am I supposed to document other programming languages?
What I had expected is some markup that doesn't make any assumptions
about syntax, i.e. I'd type exactly the legal syntax and *add* markup,
e.g. something like

   <funcsynopsis role="Python">
   <funcdef><function>foo</function>
     (<paramdef><parameter>bar</parameter>=None</paramdef>)
   </funcsynopsis>

Stripped of all markup, this yields "foo(bar=None)", something every
Python programmer would understand.

Another problem is classes and methods; there seems to be no markup
at all for that. Or did I just overlook something?
-- 
-------------------------------------------------------------------------------
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
-------------------------------------------------------------------------------


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]