[SciPy-Dev] More doc Marathon prioritization

[David Goldsmith]

On Mon, Jun 21, 2010 at 9:16 PM, David Goldsmith <d.l.goldsmith at gmail.com>wrote:

> On Mon, Jun 21, 2010 at 9:07 PM, <josef.pktd at gmail.com> wrote:
>
>> 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 ?
>>
>
> 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.
>

Just added a Key to the sheet (Column E).

DG


>
>  Several subpackages have the narrative in the tutorials.
>>
>
> => Question 3: Is that the (only) place we want them?
>
> DG
>
>
>>
>> Josef
>>
>>
>> >
>> > Thanks again!
>> >
>> > _______________________________________________
>> > SciPy-Dev mailing list
>> > SciPy-Dev at scipy.org
>> > http://mail.scipy.org/mailman/listinfo/scipy-dev
>> >
>> >
>> _______________________________________________
>> SciPy-Dev mailing list
>> SciPy-Dev at scipy.org
>> http://mail.scipy.org/mailman/listinfo/scipy-dev
>>
>
>
>
> --
> 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)
>



-- 
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...
URL: <http://mail.python.org/pipermail/scipy-dev/attachments/20100621/9ea1b314/attachment.html>