(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 / [EMAIL PROTECTED] / http://blog.ianbicking.org _______________________________________________ Doc-SIG maillist - [email protected] http://mail.python.org/mailman/listinfo/doc-sig
