[SciPy-Dev] More doc Marathon prioritization

David Goldsmith d.l.goldsmith@gmail....
Mon Jun 21 23:58:52 CDT 2010


On Mon, Jun 21, 2010 at 9:35 PM, <josef.pktd@gmail.com> wrote:

> On Tue, Jun 22, 2010 at 12:20 AM, David Goldsmith
> <d.l.goldsmith@gmail.com> wrote:
> > On Mon, Jun 21, 2010 at 9:16 PM, David Goldsmith <
> d.l.goldsmith@gmail.com>
> > wrote:
> >>
> >> On Mon, Jun 21, 2010 at 9:07 PM, <josef.pktd@gmail.com> wrote:
> >>>
> >>> On Mon, Jun 21, 2010 at 11:47 PM, David Goldsmith
> >>> <d.l.goldsmith@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/
>

The latter, I believe - whichever get's printed by:

>>> help(scipy.stats)

That's what's getting edited at
http://docs.scipy.org/scipy/docs/scipy.stats/, correct?

FTR: My triage table was constructed from an examination of:

http://docs.scipy.org/scipy/docs/scipy/

I haven't (knowingly) done anything pertaining to scipy-docs, as my
understanding of my responsibility is to the docstrings of the package's
objects, first and foremost.

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

Sounds vaguely familiar; any chance you could find that thread?

Thanks for the feedback,

DG

>
> 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@scipy.org
> >>> > http://mail.scipy.org/mailman/listinfo/scipy-dev
> >>> >
> >>> >
> >>> _______________________________________________
> >>> SciPy-Dev mailing list
> >>> SciPy-Dev@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@scipy.org
> > http://mail.scipy.org/mailman/listinfo/scipy-dev
> >
> >
> _______________________________________________
> SciPy-Dev mailing list
> SciPy-Dev@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)
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://mail.scipy.org/pipermail/scipy-dev/attachments/20100621/52378b7b/attachment.html 


More information about the SciPy-Dev mailing list