[Doc-SIG] Python docs in reST

[Ian Bicking]

(note that none of this message relates to the Python reference 
documentation...)

Michael Foord wrote:
> As a side issue - it would be nice for developers of other 
> modules/projects to be able to *easily* generate documentation that is 
> consistent with the (IMO) nice looking Python documentation.
> 
> I confess to *not* having looked into Latex markup [#]_ - so  I haven't 
> a clue how difficult it is to use, but I love reST. If Latex is *that* 
> easy to use why bother creating reST ;-)
> 
> In order to achieve this (becoming a useful documentation system for 
> Python projects) - docutils needs to be capable of handling anything 
> that is in the Python docs. So it is certainly in the interests of the 
> docutils project to address these issues... whether that means it should 
> be adopted as *the* method of documenting Python is another matter. 
> Hopefully natural selection will start to work...
> 
> Surely implementing a Python source reader (that works by introspection 
> or whatever) that extracts docstrings and inserts it *into* a reST 
> document (still a two pass process) would help as a short term measure. 
> Hmmm..... I might even implement something like that myself.

Incidentally, I just recently wrote a tool to do this... well, right now 
it creates a single document from extracted source, but it's very young, 
and it should be able to create fragments as well, for inclusion in 
other documents.  The development model, as I have time to put into it, 
will be primarily about producing the desired output, without any 
particular committment to an underlying architecture (I've already 
written two other systems which I've thrown away, so I'm trying not to 
focus too much on implementation).

It's intended to extract documentation from source that is written 
specifically with this tool in mind, and only documents things that are 
explicitly specified (using __all__ and magic attributes now, probably 
more annotations in the future).  It allows things like documenting an 
interface from another module, without including that module itself in 
the documentation anywhere.

The code:
   http://svn.pythonpaste.org/Paste/trunk/paste/docsupport/

What it currently produces:
   http://pythonpaste.org/docs/reference.html

Part of the importance to Paste is that the objects to be documented 
aren't generally directly referenced; they are put into a stack of WSGI 
middleware implicitly, are return values from functions, etc.  Even now 
the module organization of the document isn't helpful, it should be 
organized based on functionality.  Indexing is also high up on my list 
for it, including custom indexes (for Paste that includes 
domain-specific things like WSGI keys added, configuration keys used, 
middleware and servers available, etc).

-- 
Ian Bicking  /  ianb at colorstudy.com  /  http://blog.ianbicking.org