[Doc-SIG] Documenting Python, Take 2

[uche.ogbuji@fourthought.com]

Based on my meta-proposal, here is my suggestion for the Zen of Python 
documentation.

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

Module name
Module description
Global Object References
Functions
	Description
	Parameters (name and description)
	Return value (description)
Classes
	Methods (see functions, maybe flag for initializer)
	Class-level object refs
etc.

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

@version
@author
@param
@return
@exception
@see

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.


-- 
Uche Ogbuji
FourThought LLC, IT Consultants
uche.ogbuji@fourthought.com	(970)481-0805
Software engineering, project management, Intranets and Extranets
http://FourThought.com		http://OpenTechnology.org