[DOC-SIG] Status of documentation effort?

[Marc Poinot]

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:

1- Interface
   How to use the module, when, args meaning, design tips...
   With an interface langage like C++, ADA, etc... I can document
   the interface part with such informations.
   This is public information.

2- Maintenance
   How to deal with the implementation? The why of the design
   the description of private parts. In a C++ or ADA code I
   put this information in the bodies.
   This is the private information.

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 ?

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?  (?? !)    ?

> Must run on Unix, Win32, and Mac.
> 
NT (?)

> Render sub-packages for: HTMLgen2/CSS1, XML/XSL, WinHelp, MIF, text,
> etc.
etc=LaTeX

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

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

_______________
DOC-SIG  - SIG for the Python Documentation Project

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