[Doc-SIG] SGML Python docs

[Cees de Groot]

tratt@dcs.kcl.ac.uk said:
> Is it now tied in with the SGMLTools stuff posted on this sig a couple
> of weeks back?

No, and I don't think it belongs there for two reasons: first, I think that 
generating DocBook (which SGMLtools targets) is overkill; people shouldn't be 
forced to have to install Jade et al just to get usable documentation; and 
second, like POD, a Python doc generator should be part of the base Python 
distribution so that people will actually start using it.

As I'm talking anyway, here's my two cents of ideas (I shouldn't really be 
doing this, because I've been here too short and I haven't had the time to 
check the archives nor the code that's relevant...): I'd favour XML generation 
with a simple XML DTD (containing element definitions for boldface, italic, 
code, ordered and unordered list, basically HTML--). Include with Python a 
simple XML backend that can generate HTML, manpage source, ASCII and DocBook 
SGML - the latter one can then be used for the heavier stuff, like collecting 
documentation of numerous modules into one volume (eg., generate the library 
reference from the .py modules plus some SGML glue).

Regards

Cees

-- 
Cees de Groot               http://pobox.com/~cg          <cg@pobox.com>
                            http://www.sgmltools.org  <cg@sgmltools.org>
--- We're hiring Java developers => www.acriter.com