[Doc-SIG] Re: Documenting Python, Take 2

[Fred L. Drake, Jr.]

uche.ogbuji@fourthought.com writes:
 > F1) A highly-structured format for archiving and manipulation of low-level 
 > documentation (what Fred Drake is calling "microdocuments").  Example: SGML
 > or XML schema.  This format must be semantically complete, easy to
 > manipulate in code, with a broad toolset available for manipulation.

Uche,
  I'd *love* to see a good definition of "semantically complete" for
Python!  ;-)

 > F2) An author-friendly format for low-level documentation.  F2 has to be 
 > structured enough for meaningful conversion to F1, but terse enough for use
 > in in-line documentation and adoption by authors for whom F1 would be too
 > much of a chore.  Example: javadoc, POD.

  I'm working on this one, along with an extraction tool.

 > F3) An author and maintainer-friendly format for general documentation,
 > such as the Python profiler and debugger docs as well as the User guide and
 > all that.  Example: Docbook, RTF.  Abundance of author and manipulation
 > tools is important for this format.

  Yes; I think SGML/XML is probably fine for this.


 > T1: A tool for conversion from F1 to F2 and back.

  I understand the need for F2-->F1, but why F1-->F2?  It certainly
could not be general unless F1 is heavier than I imagine.  Please
provide the rationale for the F1-->F2 requirement.

 > T2: A tool for interactively querying authors for documentation elements: 
 > basically a knowledge-acquisition tool from python module experts. (Maybe
 > you can guess what one of our recent contracts has been).

  This might be cool.  We could then go from a parse tree (.py file;
F2) to skeletal F1, and then augment using the interactive tool.  In
practice, perhaps you really point the tool to the source file and
skip storing the skeletal F1 to disk if you aren't going to intervene
with a text editor at that point.  Allowing either to be accepted by
the tool is probably a good idea.  That would allow both documentation 
creation and editing within the tool.

 > T3: A tool for generating user-friendly doc-strings into python modules
 > from the information in F1.

  This sounds the same as T1 to me; do you see F2 being used outside
of docstrings?  (I've been working under the rubric that I should pull 
as much as possible out of the code to get the best possible docs when 
the programmer doesn't provide any additional information.)

 > T4: A command line tool that can display user-friendly docs from a
 > database of F1 docs, similar to perldoc.

  Agreed.

 > T5: A tool for turning F1 and F3 into the familiar Python User Guide and 
 > Library Reference, preferably with richer linking.

  That's within my current plans (i.e., I haven't written it yet).
Rich hypertext is one of the most important benefits I see for
ditching the current tool chains -- doing much through LaTeX2HTML can
be quite painful!

 > T6: A tool for generating man-pages based on F1 Documentation.  This would 
 > address the insistent crowing of Tom Christiansen about Python's "man-page 
 > envy"

  Perhaps we could ask Tom to write this?  ;)  Since Tom's last
crusade against the Python documentation, I've had one user comment
that they'd like to see man pages for Python (paraphrased: it'd be
nice to have).  Tom's the only user to say that the rest doesn't count 
(regardless of how many words he took to say it).

 > In a separate message, I'll make a proposal based on this meta-proposal.

  I look forward to it!


  -Fred

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