[Doc-SIG] Python docs in reST

[Ian Bicking]

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  /  ianb at colorstudy.com  /  http://blog.ianbicking.org