Kenneth McDonald wrote: > To me, the biggest single problem in Python documentation is that > there is no standard inline documentation format which has been > "blessed" as _the_ standard by the Python core development team. I > like Python much better than Ruby, but take a look at Ruby for a an > example of what kind of tools can be built once people have a standard > as a base. rubydoc is really, really nice
I think the community reached consensus on ReST_ some time ago -- not completely officially (though there is a PEP out there), but it's certainly the defacto standard. The docutils_ project, which ReST is a part of, is ostensibly larger than just ReST, > Whatever might be chosen or developed, we need IMHO a doc standard > that is part of the core python package, and comes with all of the > tools needed to use it. Without this, documentation of python modules > is always going to be rather ad hoc. Additionally, but conflictingly, there is a documentation tool in the standard library: pydoc_ (conflicting because it doesn't support ReST). But I'd say the primary JavaDoc-like tool would be Epydoc_ (which does support ReST, as well as its own markup language). Personally I've never seen a three-pane autogenerated reference document that I've liked. But eh... I think I'm just expecting too much from one tool. I guess one problem is that Python doesn't have good a formal notion of "public" vs "private", so a lot of cruft and implementation will show up in a autogenerated document. But, I'm feeling a need to autogenerate some documentation for Paste_, so I have to figure out some of this myself. Right now I'm thinking of building a little scraper that uses metadata specifically applicable to the project -- for instance, I want to keep indexes and make nice documentation of all the configuration values, and all the WSGI environment keys different components use. Obviously this kind of metadata is quite structured and (in the specific sense) not widely applicable. If PEAK_ was more like a tool and less like a worldview, I'd probably try to see what Phillip has done there, as I know he worked (or at least thought) about a kind of customizable system like this. But I'm afraid it's too much for me to get my head around right now :( -- anyway, I can't find it in CVS there, so maybe it never got to the point of code. .. _docutils: http://docutils.sourceforge.net/ .. _ReST: http://docutils.sourceforge.net/rst.html .. _pydoc: http://python.org/doc/current/lib/module-pydoc.html .. _Epydoc: http://epydoc.sourceforge.net/ .. _Paste: http://pythonpaste.org .. _PEAK: http://peak.telecommunity.com/ -- Ian Bicking / [EMAIL PROTECTED] / http://blog.ianbicking.org _______________________________________________ Doc-SIG maillist - [email protected] http://mail.python.org/mailman/listinfo/doc-sig
