[SciPy-Dev] More doc Marathon prioritization

Tue Jun 22 00:37:24 EDT 2010

On Tue, Jun 22, 2010 at 12:35 AM,  <josef.pktd at gmail.com> wrote:
> 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/

or another example

http://docs.scipy.org/scipy/docs/scipy.interpolate
or
http://docs.scipy.org/scipy/docs/scipy-docs/interpolate.rst/

to answer to your comment in the former

Josef
>
> 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
>>
>>
>