[DOC-SIG] Status of documentation effort?

[Friedrich, Robin K]

>----------
>From: 	Marc Poinot[SMTP:poinot@onera.fr]
>Sent: 	Wednesday, February 18, 1998 4:21 AM
>To: 	doc-sig@python.org
>Subject: 	Re: [DOC-SIG] Status of documentation effort?
>
>I'm a newcommer in the group, I've read your status and I have a
>single simple question:
>
>- What is the purpose of the doc?
>
>This may have been discussed before...my goals in documenting code are:
Pretty much the same goals as the rest of us:-)
gendoc in the past has restricted itself to the information in the doc
strings and the meta-information gathered from the module. This
traditionally will contain just the public or user level documentation.
Gendoc is targeted at generating this level. Maintenance information is
generally found in comments rather than doc strings. The maintainer of
the code is obviously looking at the source anyway, while if we do our
job right in generating user documentation the *users* of the code won't
have to.
>
...
>I can document Python code for the point [2].
>As a matter of fact, I've got a practical problem with [1]:
>How to provide the users with a public interface (as doc)?
>Something like IDL (but I don't want IDL, I want pure Python!)?
>Is it possible to imagine two doc levels ?
Yes. Let's restrict ourselves to point[1] though for gendoc.
>
>Here are my remarks about your requirements:
>
>Friedrich, Robin K wrote:
>> 
>> GENDOC 1.0 Design Requirements
>> 
>...
>> Uses import method to extract info.
>> 
>For the point [1], I guess the import is for the doc generation.
>But this implies two set of files, the code and the doc. Can we
>imagine to have a simple (raw dumb textual) description of
>the services of a class using a self-builting method in the
>module itself?  (?? !)    ?
I don't think that will be as practical as having a tool to run over
your source tree.
>
>> Must run on Unix, Win32, and Mac.
>> 
>NT (?)
That's Win32 - so yes NT.  This one's a given if we write everything in
Python.
>
>> Render sub-packages for: HTMLgen2/CSS1, XML/XSL, WinHelp, MIF, text,
>> etc.
>etc=LaTeX
OK you just volunteered;-) for the LaTeX renderer.
>
>> Renderers are passed the full structure object and walk the tree
>> generating
>> the appropriate output. Features to help tailor the content and ordering
>> of output
>> may be included in a base class AbstractRenderer. A renderer which
>> translates the
>> data into a structure suitable for import into a programming environment
>> tool like
>> PTUI might me nice too.
>> 
>Use for an Index?
Yes. Have you looked at gendoc 0.6 output? check out:
http://starship.skyport.net/crew/friedrich/HTMLgen/html/index.html
>
>> class Module:
>>     def filename():
>>     def children():
>>     def parent():
>>     def name():
>>     def documentation():
>> 
>      def ShortDocumentationForOtherModulesWhichImportMe():
>
>Or does it take place into a doc format standard?
>
>Marcvs [alias Once again, our problem is how to provide a public
>embedded
>        documentation, any hints are bienvenus]
Also required reading in this discussion will be the structured text
standard.
http://www.python.org/sigs/doc-sig/
>
>

_______________
DOC-SIG  - SIG for the Python Documentation Project

send messages to: doc-sig@python.org
administrivia to: doc-sig-request@python.org
_______________