[SciPy-Dev] Status of scipy.* docstrings

David Goldsmith d.l.goldsmith@gmail....
Sun Aug 1 16:21:12 CDT 2010


Hi, josef, and thanks!

On Sun, Aug 1, 2010 at 2:48 AM, <josef.pktd@gmail.com> wrote:

> On Sun, Aug 1, 2010 at 12:18 AM, David Goldsmith
> <d.l.goldsmith@gmail.com> wrote:
> > Hi, folks!  Except for scipy.stats, the docstrings of all sub-packages
> > immediately "below" scipy have now had autosummary directives for all
> (with
> > one exception) their objects added to them, with either the existing
> > description if there already was one, or the description pulled in by the
> > autosummary (perhaps paraphrased if necessary to satisfy the 75 character
> > restriction) if said pulling worked, or "TODO" if neither of those
> > conditions were met; scipy.stats was already partially under autosummary
> > "control" when I checked it, so I've left it alone pending further info
> as
> > to whether this incompleteness is intentional or not.  I will continue to
> > work my way down the namespace tree - at a reduced pace - but I just
> wanted
> > to announce that this ad hoc (i.e., "unofficial") milestone has been met,
> > and point out that some of the holes alluded to above can serve as
> pointers
> > to places that need work, e.g., places where the autosummary directive
> > either pulled nothing, "failed to parse" the summary, or pulled an
> > excessively long description (indicating, IIUC, a docstring w/ an
> > excessively long Brief Summary).
>
> Is there a way to handle now autosummary and similar directives in
> python modules, e.g. info.py.
>

Please clarify precisely what you mean: exactly what problem(s) are you
seeing/having?


> What's the pattern/recommendation now for content in the module
> docstring, in __init__.py or info.py, versus subpackage rst file ?
>

I don't think a formal "policy" was ever formally adopted.  I, rather
unilaterally, took it upon myself to "standardize" to using the autosummary
directive in sub-package and module docstrings on the grounds that it
assures consistency across at least two presentations: the target object
docstring and its one line summary in the auto-rendering of the docstring of
its parent namespace (unfortunately, it doesn't assure consistency in the
"terminal" presentation of the latter docstring--presently, that has to be
done manually--but maybe automation of that too can be added down the
road).  I had no qualms about making the unilateral decision to do this
because: a) I felt my reasoning for doing so was consistent w/ our general
philosophy of fighting docstring divergence, and b) my change could always
be reverted.  Anyway, there it is: if people feel that this is how we should
continue, then there are now a bunch of examples to follow; if they don't,
the changes can be reverted and a different approach to consistency and
minimal maintenance can be proposed.  As far as narrative content in these
top level docstrings is concerned, I did not provide any where it did not
already exist - that open issue is still open AFAIC.

DG


>
> (I'm still trying to catch up with recent changes.)
>
> >
> > Thanks for all you do (and thanks for all the kudos that have come in
> post
> > my resignation announcement).
>
> Also a big thank you from me, especially for getting a more consistent
> structure into the docs.
>
> Josef
>
>
> >
> > DG
> >
> > --
> > Mathematician: noun, someone who disavows certainty when their
> uncertainty
> > set is non-empty, even if that set has measure zero.
> >
> > _______________________________________________
> > 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/20100801/57a8b306/attachment.html 


More information about the SciPy-Dev mailing list