[PYTHON DOC-SIG] Re: DTD's for Python (fwd)

[Jim Fulton]

Mark Hammond wrote:
> 
> But would it make sense to beef up gendoc? 

Yes.

> gendoc could parse the
> .py, and possibly other special purpose doco files.
> 
> This would seem perfect for the library doco - you end up with a very
> nice tool built in Python, and also a whole lot more documentation
> that has the same "look and feel" as the .lib documentation.
> 
> For reference documentation especially, I feel it important to keep
> it close to the sources.  This may not be appropriate for the
> tutorial etc, but it seems we are missing a "general" opportunity to
> really further beef up _all_ (including future :-) Python documentation.

I agree alot.  I think library documentation should be generated from
doc strings.  This keeps the documentation in sync with the source and
with on-line browsing tools.  Documentation strings are also much
simpler 
to write, as they are a simple form of structured text.

I will probably never contribute any documentation
if I have to write it in Tex, or some variant.

As a side note, I don't think parsing the code should be necessary
either.
I thing it should be possible to import a module and discover all of the
documentation from exported objects and their attributes.  I've been
very
successful with this myself.  I've been able to do this with extensions
too, 
although it requires a richer extension model, like ExtensionClass or
MESS.

Jim



_______________
DOC-SIG  - SIG for the Python Documentation Project

send messages to: doc-sig@python.org
administrivia to: doc-sig-request@python.org
_______________