[Doc-SIG] Documenting Python, Take 2
Thu, 25 Nov 1999 02:27:29 -0700
Based on my meta-proposal, here is my suggestion for the Zen of Python
My vote for format F1 is an XML schema. Fred's wonder about "semantically
complete is duly noted. Let's have this as a start
Global Object References
Parameters (name and description)
Return value (description)
Methods (see functions, maybe flag for initializer)
Class-level object refs
Fred's example from his original message is a decent start. Remember that F1
needn't be terse.
My vote for F2 is a modification of javadoc. It's very well known and very
successful. Off-head, we should be able to use
without modification. "@see" would be _very_ nice, wouldn't it?
We would need some additions, such as @module.
My vote for F3 is docbook. There are tools to turn docbook into HTML, GNU
info, *roff (man pages), ps, pdf, etc. There is an O'Reilly book out on it,
an emacs mode, etc.
I would volunteer to write a python-javadoc to XML converter. Note: I'm not
saying I won't help unless my suggestions are accepted. I'm just volunteering
for a known quantity that I know I can handle.
FourThought already has an internal tools for querying an author for
documentation automatically. We could adapt this to the new DTD that is
determined, and donate it to the cause.
FourThought LLC, IT Consultants
Software engineering, project management, Intranets and Extranets