[Doc-SIG] Python PODs?

Moshe Zadka Moshe Zadka <mzadka@geocities.com>
Fri, 20 Aug 1999 22:59:24 +0300 (GMT+0300)


Hi.

The recent flamewar on c.l.py about lack of man pages got me thinking
about a new "backend" for Python documentation, which would reflect
Python's nature, while being amenable for auto-processing. The basic
format would be POD (Perl's plain old documentation format), which is
quite easy to parse. The Pythonic namespace hierarchy 
(package->module->object->methods) could be reflected in directory
structure

I.e.,
urllib/
	---.pod (general information about the module)
	urlopen.pod
	URLOpener/
		---.pod (general information about the class)
		__init__.pod (description of init method)

Then, use of pod2man/pod2text with appropriate wrapping would mean I 
could have

pythondoc urllib (show urllib/---.pod)
pythondoc urllib.URLOpener.__init__ (show urllib/URLOpener/__init__.pod)

I would be all-to-happy in helping to write such a back-end, we just
need to make sure

1. The front-end is stable, and easily parsable (SGML ain't, XML is)
2. The front-end has enough information to do that easily (not really
sure)

What do you think?

A preliminary module to make genereating PODS look just like generating
XML (so the convertor would be written the way XML->XML translators are
written) is in http://starship.python.net/crew/moshez/POD.py 
(It's not thoroughly debugged, but it passed the simple _test() well
enough)
--
Moshe Zadka <mzadka@geocities.com>. 
I'm not anti-Microsoft -- Microsoft is anti-me
(Anonymous Coward on /.)