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

Jim Fulton Jim@digicool.com
Thu, 13 Feb 1997 06:50:48 -0500

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


> 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
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
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
successful with this myself.  I've been able to do this with extensions
although it requires a richer extension model, like ExtensionClass or


DOC-SIG  - SIG for the Python Documentation Project

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