[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