[SciPy-Dev] More doc Marathon prioritization

Tue Jun 22 00:35:23 EDT 2010

On Tue, Jun 22, 2010 at 12:20 AM, David Goldsmith
<d.l.goldsmith at gmail.com> wrote:
> 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?

Are you talking about the module docstrings in info.py which are
imported into __init__.py __doc__ or about the rst file which contains
the sub-package description?
http://docs.scipy.org/scipy/docs/scipy-docs/stats.rst/  or
http://docs.scipy.org/scipy/docs/scipy.stats/

We had the discussion once about the duplication but I don't think or
don't remember whether it got resolved.

I would put all effort into the rst file and keep info at most as
basic listing. autosummary directives in info.py wouldn't help because
they are not available in the interpreter, and I don't think sphinx
would pick them up (but that I don't know).

As for content, for stats, I would like to see mainly a brief
description of the groups of functions, descriptive, tests (tests for
mean, test for variation, tests for correlation), trim ...
Any narrative longer than a basic description would make the front
page of the sub-package much too long.

Josef

>>
>> 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)
>
> _______________________________________________
> SciPy-Dev mailing list
> SciPy-Dev at scipy.org
> http://mail.scipy.org/mailman/listinfo/scipy-dev
>
>