[PYTHON DOC-SIG] Re: Do reference/user docs exist for the Py* API?

[Robin Friedrich]

|> From: Skip Montanaro <skip@automatrix.com>
|> 
|> Okay, Guido agrees the docs I'm looking for are needed:
|> 
|>    > I haven't been able to find any sort of reference or user documentation for
|>    > the Python C API other than the extending/embedding manual and the comments
|>    > in Include/abstract.h.  Does anything else exist? ...
|> 
|>    Someone just donated a LaTeX file containing a translation from
|>    abstract.h (mostly), but apart from that, this stuff is still sorely
|>    missing...
|> 
|>    > At this point I'm mostly interested in a reference document ...
|>    > Longer term, I'd like to see some user documentation with short code
|>    > examples ...
|>    
|>    All totally agreed...  We need more volunteer help to complete this
|>    job!

The user documentation you seek will probably be met by the two books 
to be on the bookselves RSN;-)  As for the definitive reference, I agree
100%; we need a big upgrade to the Extending & Embedding docs.

|> 
|> I'd like to generate one or more template documents automatically from the C
|> source or some other easily created template file that I can then make
|> available to people with an interest in completing individual sections.  I
|> don't want to get into a quagmire right off the bat, so I will initially
|> move this discussion from the main list to the doc-sig@python.org list.
|> (Don't worry, I'll move it back when I need more help... :-) Would someone
|> involved with the DOC-SIG (Michael McLay perhaps?)  give me a quick
|> brain-dump of the current state of the musings on the DOC-SIG, especially
|> about issues of documentation format, input source, etc?  I've subscribed to
|> the doc-sig at this point, so further discussion should take place there.
|> I'll also try and wade through the list's archives.
|> 
|> Thx,
|> 
|> Skip Montanaro   

The skinny recently has been the proposition that we come up with a 
new standard documentation format for the distribution docs. Currently
things are baselined in LaTeX and other formats are spun off from that.
I have argued that we should switch over to FrameMaker as the baseline
tool. As I sit here I am working to steamline such an effort with some
tools to aid the LaTeX->FrameMaker conversion. (Already finished the 
tutorial but that was easy as it didn't have an index.) At this point
I would recommend _not_ using LaTeX markup. If we/you create a tool
to generate docs for the API let's tune it for FrameMaker. We could 
either use the MML (maker markup language) or go through MIF (maker
interchange format). The former is a very simple paragraph markup
resembling HTML and the later is a full blown markup supporting
everything Frame supports.

=================
DOC-SIG  - SIG for the Python Documentation Project

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