[SciPy-Dev] More doc Marathon prioritization
Warren Weckesser
warren.weckesser@enthought....
Tue Jun 22 07:33:19 CDT 2010
David Goldsmith wrote:
> On Mon, Jun 21, 2010 at 9:35 PM, <josef.pktd@gmail.com
> <mailto:josef.pktd@gmail.com>> wrote:
>
> On Tue, Jun 22, 2010 at 12:20 AM, David Goldsmith
> <d.l.goldsmith@gmail.com <mailto:d.l.goldsmith@gmail.com>> wrote:
> > On Mon, Jun 21, 2010 at 9:16 PM, David Goldsmith
> <d.l.goldsmith@gmail.com <mailto:d.l.goldsmith@gmail.com>>
> > wrote:
> >>
> >> On Mon, Jun 21, 2010 at 9:07 PM, <josef.pktd@gmail.com
> <mailto:josef.pktd@gmail.com>> wrote:
> >>>
> >>> On Mon, Jun 21, 2010 at 11:47 PM, David Goldsmith
> >>> <d.l.goldsmith@gmail.com <mailto: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
> <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?
>
I asked about "package/info.py" and "doc/source/package.rst" back in April:
http://mail.scipy.org/pipermail/scipy-dev/2010-April/014065.html
My conclusion at that time was that both had to be maintained, despite
the apparent duplication.
Warren
> 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 <mailto:SciPy-Dev@scipy.org>
> >>> > http://mail.scipy.org/mailman/listinfo/scipy-dev
> >>> >
> >>> >
> >>> _______________________________________________
> >>> SciPy-Dev mailing list
> >>> SciPy-Dev@scipy.org <mailto: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 <mailto:SciPy-Dev@scipy.org>
> > http://mail.scipy.org/mailman/listinfo/scipy-dev
> >
> >
> _______________________________________________
> SciPy-Dev mailing list
> SciPy-Dev@scipy.org <mailto: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)
> ------------------------------------------------------------------------
>
> _______________________________________________
> SciPy-Dev mailing list
> SciPy-Dev@scipy.org
> http://mail.scipy.org/mailman/listinfo/scipy-dev
>
More information about the SciPy-Dev
mailing list