[Doc-SIG] Python docs in reST
ianb at colorstudy.com
Thu May 26 18:57:05 CEST 2005
(note that none of this message relates to the Python reference
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.
What it currently produces:
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
More information about the Doc-SIG