[SciPy-Dev] More doc Marathon prioritization

[David Goldsmith]

Hi, folks!  Joe and I would like to prioritize SciPy's top-most objects'
docstrings, i.e., those of the sub-packages and modules primarily, and work
our way down.  As groundwork for this approach, I've created the following
triage table:

https://spreadsheets.google.com/ccc?key=0AvCyyT1vWOKJdENtS1lGandfUFRqQU01R2VMSnB6SXc&hl=en

some of it is subjective, most of it, hopefully, is objective.

Mainly what I hope to achieve w/ this post is twofold:

A) Get a few questions (see below) answered regarding general guidelines for
completing these docstrings; and

B) Recruit subject-area experts to complete these top-level docstrings,
subject to the guidelines I hope to elicit below.

Questions:

1) Presently, most of these top-level docstrings consist either completely
or almost completely of sub-package/module content listings w/ brief (i.e.,
typically one-line) descriptions; almost all the rest consist of some amount
(typically meager) of narrative description, with no content listing; no
more than a few have both narrative and a content listing.  So, the
questions here are, what should these docstrings contain: a narrative
description of the object; a content listing; both; or is there some reason
it should vary from object to object?  (Hopefully this last is not the
answer...)  If a narrative description (either solely or in combination with
a content listing) can we formalize what these narratives should
contain/look like?  (Robert Kern's docstring for odr might be a good
nominee/starting point for a sub-package/module docstring standard, at least
for the narrative part.)

2) If these docstrings should consist of or contain a sub-package/module
content listing, shouldn't we be using the Wiki's .. autosummary:: function,
instead of creating these listings manually (as I think is uniformly the
case in SciPy presently)?

So, once we get these things straightened out (or even before then, on your
own machine if you think narrative content is warranted and you feel that
you can provide it - just hold on to it 'til we get these issues resolved),
I hope there will be a stampede of expertise just knocking the doors down to
whip these buggers into shape! :-)

DG

PS: For your convenience, here's the list of top-level objects (potentially)
needing work:

cluster
constants
fftpack
integrate
interpolate
io
lib
linalg
maxentropy
misc
ndimage
odr
optimize
setupscons
signal
sparse
sparse.linalg
sparse.linalg.dsolve
sparse.linalg.dsolve.umfpack
sparse.linalg.eigen.arpack
sparse.linalg.eigen.lobpcg
spatial
special
stats
weave

Thanks again!
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/scipy-dev/attachments/20100621/a947cda1/attachment.html>