[SciPy-Dev] Status of scipy.* docstrings
Sun Aug 1 16:21:12 CDT 2010
Hi, josef, and thanks!
On Sun, Aug 1, 2010 at 2:48 AM, <email@example.com> wrote:
> On Sun, Aug 1, 2010 at 12:18 AM, David Goldsmith
> <firstname.lastname@example.org> wrote:
> > Hi, folks! Except for scipy.stats, the docstrings of all sub-packages
> > immediately "below" scipy have now had autosummary directives for all
> > 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
> > 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
> > 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
> > 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
> 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.
> (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
> > my resignation announcement).
> Also a big thank you from me, especially for getting a more consistent
> structure into the docs.
> > DG
> > --
> > Mathematician: noun, someone who disavows certainty when their
> > 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
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...
More information about the SciPy-Dev