[Doc-SIG] Documenting Python, Take 2
uche.ogbuji@fourthought.com
uche.ogbuji@fourthought.com
Tue, 23 Nov 1999 14:29:59 -0700
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
http://www.python.org/pipermail/doc-sig/1999-September/000726.html
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.
FORMATS:
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.
CUSTOM TOOLS:
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
envy"
In a separate message, I'll make a proposal based on this meta-proposal.
--
Uche Ogbuji
FourThought LLC, IT Consultants
uche.ogbuji@fourthought.com (970)481-0805
Software engineering, project management, Intranets and Extranets
http://FourThought.com http://OpenTechnology.org