[Doc-SIG] Documenting Python, Take 2 (RE-POST)
Wed, 24 Nov 1999 19:00:45 -0700
Pardon me if you get this twice, but I had problems with mail at python.org
Sorry it took so long to get around to this.
I think my earlier approach (let's call it a meta-proposal) to settling on a
Python documentation system still applied, with some modifications.
My original posting is at
But in light of the current discussion and concerns that have been raised,
changes are in order.
Python Documentation Python Meta-Proposal
I think in essence we must quickly decide on a set of documentation formats
and enabling tools, and then answer the questions of how to get there from
where we are. A step-wise transition, as Paul suggests, is fine, but I think
it is important for us all to have a vision of where we're going.
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.
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.
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.
T1: A tool for conversion from F1 to F2 and back.
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).
T3: A tool for generating user-friendly doc-strings into python modules from
the information in F1.
T4: A command line tool that can display user-friendly docs from a database of
F1 docs, similar to perldoc.
T5: A tool for turning F1 and F3 into the familiar Python User Guide and
Library Reference, preferably with richer linking.
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
In a separate message, I'll make a proposal based on this meta-proposal.
FourThought LLC, IT Consultants
Software engineering, project management, Intranets and Extranets