On 9/2/08, David Farning <[EMAIL PROTECTED]> 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 _______________________________________________ Sugar mailing list [email protected] http://lists.laptop.org/listinfo/sugar
