[XML-SIG] PyDoc/XML?

[uche.ogbuji@fourthought.com]

> >>The Python community will one day have its own package used for the
> ......>
> >Here is what we've very tentatively set up for FourThought:

<DTD and XSL snipped>

> >
> >What does everyone think?  Could we hack the hell out of it on this list and 
> >adopt it for standard Python docs.

> I'm just eavesdropping on your conversation, trying to understand how
> this would work. If I understand correctly you're proposing an 'autoDoc'
> facility for Python along the lines of JavaDocs. But I don't see how XML
> is used to mark-up the Python source code. Is that included in your idea?

I was not yet proposing a mechanism for generating Python docs, just a format 
for the eventual stand-alone docs.  I personally don't like the current vogue 
in document/code fusion.  Yes, I like modules to be self-documenting and all 
that, but I've found having large swathes of high-level docs scattered about a 
module to be a tremendous hindrance.

I think that in this connected Internet world, it's better to simply link from 
the module to on-line docs.  Yes this is not ideal, what if there are network 
problems, etc. but it's the trade-off I prefer.

FourThought currently uses the separate-but-linked module doc approach, and we 
use the DTD abd Stylesheet I presented.  As we develop our XLink tools, we 
have even cooler ideas for integrating code and docs, but once again, right 
now all I'm trying to do is propose a format.

If we can agree on a format, then the auto-doc folks can generate the XML from 
their doc-strings in a similar approach to Javadoc, and others can simply 
enter the docs directly into Web- or command-line tools.

> In other words, is it possible to use XML as a markup language inside the
> comments of another language etc. I seem to recall that this is done in
> SGML but haven't heard of it in XML.

Where's the technical problem?


#!/usr/bin/python
"""
<module name='foo'>
<description>A collection of k-RAD routines for the very 3733T</description>
</module>
"""

class bar:
	"""
	<class name='bar'>
	<description>A class all on its own</description>
	</class>
	"""
	def __init__():

etc.

I don't recommend it: it is cluttered, which is why I advocate 
separate-but-linked docs, but it's perfectly legal, and it wouldn't be 
terribly difficult to write a script that extracts pure XML from it.

-- 
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