[sugar] Sugar API documentation

[Janet Swisher]

On 9/2/08, David Farning <dfarning at sugarlabs.org> wrote:
> After some discussions with Janet Swisher last week I thought it was
> time to take another stab at API documentation for sugar.
>
> Background:
> Several months ago I started experimenting with several tools to
> generate API documentation from the source code.
>
> After several misguided efforts, I settled on the following work flow to
> build the docs:
>
> 1. Build sugar via sugar jhbuild.
> 2. run epydoc against the install direrectoy built by jhbuild.
> 3. Upload the contents of apidocs/*  to api.sugarlabs.org .
> 4. Repeat.
>
> The work flow to contribute to the documentation is as follows:
> 1.  Pull git tree.
> 2.  Add documentation.
> 3.  Submit patch to SL.
>
> What should/can we do to improve this workflow?  Cause right now no work
> is flowing;(
>
> Another possibility is to use pydocweb.  You can see an example at
> http://sd-2116.dedibox.fr/pydocweb/wiki/Front%20Page/ .
>
> Janet, could you point us to a good style guide?  There seem to be as
> many way to document python as there are open source projects.

The style guide for SciPy is pretty good:
http://projects.scipy.org/scipy/numpy/wiki/CodingStyleGuidelines#docstring-standard

It has perhaps more detail than you need for Sugar, such as equations,
references, and index tags. (Even SciPy doesn't actually use the index
tags.)  I recommend these strategies:

* Use reStructured Text.
* Use explicit, standard headings (omitted if irrelevant).
* Use definition lists for parameters, attributes, and the like. This
uses a few more lines than bullet lists, but it's worth it for
readability.
* Include meaningful examples wherever possible.

If you have zilch for docstrings, you will need to make this a major
focus. The SciPy folks made it a doc "marathon" (as opposed to
"sprint"). Joe Harrington's slides about it are here:
http://conference.scipy.org/static/wiki/joe_harrington_docmarathon.pdf

Some suggestions:

* Submit bug tickets against undocumented modules. That way they are tracked.
* If someone submits a patch, ask them to write docstrings for the
relevant code---not as a penalty, but because they had to understand
that function/class/etc. to make the fix. Capture that knowledge, so
others don't have to work so hard in future.
* Once you have docstrings, review them whenever the code changes, to
ensure they sync.
* For new APIs, write the docstrings and tests first. At the very
least, don't consider it done without them.
* Offer incentives (I still haven't gotten my SciPy Marathon t-shirt,
grumble, mutter)


Cheers,
Janet