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

[uche.ogbuji@fourthought.com]

> 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!  ;-)

OK, I overstated it.  A "semantically-complete" format would likely have to 
document all the nonterminals of the Python grammar.  Let's say "reasonably 
complete".

>  > 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.

What does it look like?

>  > 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.

Repeating myself, I vote Docbook.

>  > 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.

My thinking was that some users would appreciate the concise form in their 
distro for quick reference without weighing doen their modules (and memory 
foot-print) with the heavyweight F1.

>  > 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.

Well, I hadn't thought of the parse-tree angle, though that would be cool.  
The internal tool FourThought has in this vein is merely a menu-driven 
approach.  The author selects "add new function", "modify class", and all 
that.  It's up to him or her to determine the elements to be documented.  We 
have plans for a web-i-fied version of 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.)

No.  F2 in my mind is not user-friendly.  I'm talking about something that 
converts "@param" to "parameter" with some salsa and bean dip tossed in to 
make it all palatable.

>  > 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).

Then let's just leave off that bit.  Of course, if we use Docbook, making man 
pages should be no great endeavor.


-- 
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