[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 /.)