[Docutils-users] Programming reference documentation

[Ian B. <ia...@co...>]

I'm working with the Webware project (webware.sf.net), and we really
need some cohesive reference documentation, aimed particularly at the
public interfaces.  I'm wondering if anyone is using docutils for this
now... if so, I'd like to see how it's working.  It's not entirely clear
to me what docutils status is (I've used reST a lot, but not much else).

Some options I've considered, in order of complexity:
* Writing the whole thing in reST, separate from the code itself.  The 
  writing wouldn't be so bad, but the maintenance would be more 
  difficult.
* Splitting it up into modules, and putting the entire reference 
  documentation in the module docstring.
* Using internal references in those docstrings, so I could effectively
  include the docstrings from other portions of code (classes, methods, 
  etc).

One thing I *don't* like is reference documentation in the style of
pydoc.  To me it's too automatic, and generally too hard to follow.  I
find reference documentation with some framework of text (lead-in
paragraphs, categorization, etc) to be much better.  There are also
methods which, while "public" aren't actually useful, and I don't think
those should be documented -- they are just distracting.

So the last option is the one I like the most.  But I doubt it's in
place.  I've already decided I'm not going to get the reference
documentation done for the next release (there's other documentation
that needs to be written, and documentation is tiring :), so I don't
plan to use this in the short term and I could put some work into
producing a system I like.

My vision for a docstring-based reference documentation would probably
look like:

"""
Module
======

This module does X, Y, Z.  Most work will be done through the class:

.. docstring:: MainClass

In certain cases you may wish to access the functionality separately, 
yada yada yada, and may wish to use:

.. docstring:: some_function
.. docstring:: some_other_function
"""

class MainClass:
    """
    Recursively we continue, now with methods:

    .. docstring:: MainClass.some_method
    """



How far away might this be?  Are there better alternatives already in
place, or planned on?  Does someone experienced in writing reference
documentation think this is the wrong way to go about it?


-- 
Ian Bicking           Colorstudy Web Development
ia...@co...   http://www.colorstudy.com
PGP: gpg --keyserver pgp.mit.edu --recv-keys 0x9B9E28B7
4869 N Talman Ave, Chicago, IL 60625 / (773) 275-7241