[Pipet Devel] Documentation Question

Brad Chapman chapmanb at arches.uga.edu
Mon Jan 17 09:04:02 EST 2000

Hey all!
	I was just doing some thinking about the code base of Loci and how
it would be pretty hard to access right now if you wanted to start
programming on Loci, since you'd pretty much have to go through it all by
hand and figure out what was going on. This made me start thinking about
some solutions, and the one I thought of was trying to find a javadoc type
tool for python; that is, a tool that would automatically extra comments
from code and create HTML, etc. files from it.
	Well, what I came up with is, appropriately enough, pythondoc
(http://starship.python.net/crew/danilo/pythondoc/). Of course, it has
almost no documentation, but I looked through the examples and made up a
little tester class, and got it working. Basically, it extracts the doc
strings. For those who don't know (I didn't as of yesterday!), doc strings
are comments under the definition of a function or class enclosed in """s,
as in:

def myfunction(self):
""" Here is my doc string """
	...whatever the function does

Anyways, it will take the doc strings and function and class names and
generates either HTML4 or XML output (I have examples of this output for my
little test if anyone would like to see) It can also take special stuff
within the doc strings to make the output nicer. On the python DOC-SIG page
(http://www.python.org/sigs/doc-sig/status.html) they give a description of
the special symbols you can use.
	Of course, I can't test it on my current code because, like an
idiot/new python programmer, I didn't use doc strings (but instead made my
comments in the C++ way I learned, before the function). However, I imagine
that it could be used relatively painlessly to create some HTML pages so at
least people coming into Loci and wanting to program would have an easy way
to get an idea of what all of the code does.
	Does anyone else think this would be a good idea to explore
further? I know that Gary probably has ideas, and I also remember reading
docbook markup mentioned on the list earlier on. It would probably be not
too impossible to convert the XML generated by python doc into docbook XML,
which might make it easy to put this stuff on the web pages.
	Anyways, I'd like to try and get this hashed out so I can do the
right thing WRT documentation as I continue to code. Any comments, thoughts
are very welcome!


More information about the Pipet-Devel mailing list