[SciPy-Dev] More doc Marathon prioritization

[josef.pktd at gmail.com]

On Mon, Jun 21, 2010 at 11:47 PM, David Goldsmith
<d.l.goldsmith at gmail.com> wrote:
> 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


Is there a legend for the abbreviations/acronyms ?
What does: 13 NE, 1 BW Modules; 1 BW, 2 NW(R) Classes; 48 NE, 2 BW, 48
BW Functions  mean ?


Several subpackages have the narrative in the tutorials.

Josef


>
> Thanks again!
>
> _______________________________________________
> SciPy-Dev mailing list
> SciPy-Dev at scipy.org
> http://mail.scipy.org/mailman/listinfo/scipy-dev
>
>