[SciPy-Dev] Status of scipy.* docstrings

[josef.pktd at gmail.com]

On Sun, Aug 1, 2010 at 5:21 PM, David Goldsmith <d.l.goldsmith at gmail.com> wrote:
> Hi, josef, and thanks!
>
> On Sun, Aug 1, 2010 at 2:48 AM, <josef.pktd at gmail.com> wrote:
>>
>> On Sun, Aug 1, 2010 at 12:18 AM, David Goldsmith
>> <d.l.goldsmith at 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.

My impression was that module docstrings, in __init__.py and info.py
are mainly for the commandline/interpreter, and I thought for most
subpackages they are or were not included in the sphinx rendered docs.
In this case, autosummary would be noise in the interpreter and not
picked up by sphinx, which uses the corresponding rst files.

(But I lost a bit the overview how and which parts interpreter,
doceditor and sphinx render.)

Josef


>
> 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 at scipy.org
>> > http://mail.scipy.org/mailman/listinfo/scipy-dev
>> >
>> >
>> _______________________________________________
>> SciPy-Dev mailing list
>> SciPy-Dev at 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 at scipy.org
> http://mail.scipy.org/mailman/listinfo/scipy-dev
>
>