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