[SciPy-Dev] More doc Marathon prioritization
Mon Jun 21 23:16:38 CDT 2010
On Mon, Jun 21, 2010 at 9:07 PM, <firstname.lastname@example.org> wrote:
> On Mon, Jun 21, 2010 at 11:47 PM, David Goldsmith
> <email@example.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
> > our way down. As groundwork for this approach, I've created the
> > triage table:
> > 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
> > 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
> > or almost completely of sub-package/module content listings w/ brief
> > typically one-line) descriptions; almost all the rest consist of some
> > (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
> > it should vary from object to object? (Hopefully this last is not the
> > answer...) If a narrative description (either solely or in combination
> > 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
> > 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::
> > 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
> > 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
> > I hope there will be a stampede of expertise just knocking the doors down
> > whip these buggers into shape! :-)
> > DG
> > PS: For your convenience, here's the list of top-level objects
> > 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 ?
Sorry: NE = Needs editing, BW = Being written, NR = Needs review, NW(R) =
Needs work (reviewed), NR(R) = Needs review (revised),
so 13 NE, 1 BW Modules means 13 Modules at Needs editing status, 1 Module at
Being written status, etc.
Several subpackages have the narrative in the tutorials.
=> Question 3: Is that the (only) place we want them?
> > Thanks again!
> > _______________________________________________
> > SciPy-Dev mailing list
> > SciPy-Dev@scipy.org
> > http://mail.scipy.org/mailman/listinfo/scipy-dev
> SciPy-Dev mailing list
Mathematician: noun, someone who disavows certainty when their uncertainty
set is non-empty, even if that set has measure zero.
Hope: noun, that delusive spirit which escaped Pandora's jar and, with her
lies, prevents mankind from committing a general suicide. (As interpreted
by Robert Graves)
-------------- next part --------------
An HTML attachment was scrubbed...
More information about the SciPy-Dev