[Doc-SIG] Approaches to structuring module documentation

[Fred L. Drake, Jr.]

Paul Prescod writes:
 > I think we want to be able to slice and dice the documentation with
 > tools like Zope, 4XSLT, xt.exe and Internet Explorer 5.0

  An excellent point.  It would be nice to be able to use something
other than PyDOM to manipulate the Python documentation!  ;-)

 > Would the right compromise be to have very specific documentation inside
 > the Python and relatively generic documentation outside?

  It's not such a clean division, I think.  I'm not doing anything
about extension modules, so I need to be able to provide documentation 
about those modules outside the source code.

 > The reason I proposed that we might need a grammar change is because
 > when I last thought about this I couldn't figure out how to document
 > parameters without repeating their names. Maybe that's not such a
 > significant thing though. Also, I was trying to avoid using comments
 > because I wanted the same documentation to be available as docstrings.

  I don't think it's really significant; we can't use an IDREF
attribute in SGML/XML without repeating the ID assigned to the target, 
and the locality of reference is a much greater problem there.  The
Python Tutorial and Guido's "Python Style Guide" essay both describe
some ways to format docstrings such that information extraction is
isn't too hard; those guidelines can be augmented a bit and combined
with limited markup using something that looks like the paragraph-
level analysis from the old structured-text discussion a more explicit 
(but minimal) markup similar to POD's C<...> for inline constructs.
  This sort of in-source documentation, with a little intelligent
analysis, can be used to generate XML, HTML, or whatever fairly
easily.  If a good module-reference DTD can be created (even if part
of a macro-document DTD), that can provide for both the XML output
from the extraction tool and an authoring format for extension modules 
(or other modules if the author has reasons for not using the
in-source documentation; the doc author may work for a different
organization, etc.).


  -Fred

--
Fred L. Drake, Jr.	     <fdrake@acm.org>
Corporation for National Research Initiatives