[PYTHON DOC-SIG] Re: DTD's for Python (fwd)
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: email@example.com
administrivia to: firstname.lastname@example.org