[Doc-SIG] Python docs in reST
Ian Bicking
ianb at colorstudy.com
Tue May 17 23:31:05 CEST 2005
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
More information about the Doc-SIG
mailing list