[SciPy-Dev] "Census" of scipy docstrings needing editing attention

[David Goldsmith]

On Tue, May 4, 2010 at 5:04 PM, Warren Weckesser <
warren.weckesser at enthought.com> wrote:

> Is there an explanation somewhere of the connection between the
> docstrings in the source and the docstrings visible at docs.scipy.org?
> I've made an assortment of changes (via svn) in scipy.linalg and
> scipy.signal, including the module-level docstrings, but I don't see the
> changes on the web page.  For example,
>    http://docs.scipy.org/scipy/docs/scipy-docs/linalg.rst/
> is not up to date.
>

Just to be sure: you actually opened up the docs in question in the Wiki -
as opposed to merely judging by their background color - correct?  (Via the
Wiki is the only way to update the status of a docstring, whether or not you
edit it there, i.e., if you edit a docstring in source and commit the change
in svn, the Wiki will still show the docstring as being in Needs editing (or
Being written, or whatever).

More generally, and in full recognition of the fact that it's not as
convenient to do it this way, "we" really strongly prefer docstrings to be
edited via the Wiki.  Why?  Well, among other reasons, perhaps the most
important is that the Wiki was intentionally and carefully designed to
"enforce" as many strictures of the Docstring Standard as possible.  (I put
enforce in quotes because it allows you to submit non-conforming changes,
but it complains about them loudly in red, so anyone who looks at the
docstring later in the Wiki, e.g., a reviewer, will be able to tell at a
glance if a docstring is non-conforming).

The "proper" thing to do at this point is to open up for editing in the Wiki
the docstrings you edited elsewhere and cut-and-paste your work there.  Add
a comment documenting what you've done, preview, if there are
mark-up/standard compliance problems, fix them, etc., etc., and finally, if
you regard the result as ready for review, change the status accordingly (or
change it to being written if you save changes but don't yet regard it as
"finished").  Obviously, all I can do is ask you to do this...

DG


>
> Warren
>
>
> David Goldsmith wrote:
> > Hi, all.  Joe asked me to prepare this, and I thought it might be of
> > "universal" interest to those working on the docs.  Following each
> > milestone is the number of docstrings therein needing editing
> > attention, i.e., in either the "Needs editing" or the "Being Written"
> > state (based solely on their background color), as of today, May 4, 2010.
> >
> > All docstring from http://docs.scipy.org/scipy/docs/. 2584
> >
> > Milestones/Milestones_1
> > <http://docs.scipy.org/scipy/Milestones/Milestones_1/> Cluster,
> > Constants 54
> >
> > Milestones/Milestones_2
> > <http://docs.scipy.org/scipy/Milestones/Milestones_2/> FFT, Integration
> 58
> >
> > Milestones/Milestones_3
> > <http://docs.scipy.org/scipy/Milestones/Milestones_3/> Interpolation 77
> >
> > Milestones/Milestones_4
> > <http://docs.scipy.org/scipy/Milestones/Milestones_4/> Input / Output
> > 254 (most in io.matlab)
> >
> > Milestones/Milestones_5
> > <http://docs.scipy.org/scipy/Milestones/Milestones_5/> Blas, Linear
> > Algebra 130
> >
> > Milestones/Milestones_6
> > <http://docs.scipy.org/scipy/Milestones/Milestones_6/> Max. Entropy,
> > Misc., Image Manip. 173
> >
> > Milestones/Milestones_7
> > <http://docs.scipy.org/scipy/Milestones/Milestones_7/> Ortho. dist.
> > regr., Optimization 100
> >
> > Milestones/Milestones_8
> > <http://docs.scipy.org/scipy/Milestones/Milestones_8/> Signal
> > processing 119
> >
> > Milestones/Milestones_9
> > <http://docs.scipy.org/scipy/Milestones/Milestones_9/> Sparse Matrices
> 325
> >
> > Milestones/Milestones_10
> > <http://docs.scipy.org/scipy/Milestones/Milestones_10/> Spatial
> > Algorithms., Special funcs. 266
> >
> > Milestones/Milestones_11
> > <http://docs.scipy.org/scipy/Milestones/Milestones_11/> Statistical
> > functions 473
> >
> > Milestones/Milestones_12
> > <http://docs.scipy.org/scipy/Milestones/Milestones_12/> Image Array
> > Manipulation, Convolution 47
> >
> > Milestones/Milestones_13
> > <http://docs.scipy.org/scipy/Milestones/Milestones_13/> C/C++
> > Integration 508
> >
> >
> > FWIW,
> >
> > 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.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/scipy-dev/attachments/20100504/e1e748fc/attachment.html>