[Doc-SIG] Approaches to structuring module documentation

[Bill Janssen]

Well, I might as well put in my two cents worth.

The GNU Info versions of the Python documentation are the most
important to me, as I can put those right into my Emacs and have them
at the tip of my fingers while programming.  Whatever solution is
found, I'd like to see that continued.

There's some logic to javadoc, I suppose, in that the most common
problem with documentation is that it goes out of date, because the
modifier just changes the code.  If the documentation is mixed with
the code, perhaps that probability is reduced (though I'm not aware of
any studies that show this to be true).  Though something like
Literate Programming might be a better system.  Perhaps adapting a
system like Noweb (http://www.eecs.harvard.edu/~nr/noweb/) would be of
help.  The home page lists a number of programming languages, but not
Python.

Bill