[SciPy-dev] Question about editing docs

josef.pktd@gmai... josef.pktd@gmai...
Tue May 12 15:47:41 CDT 2009


On Tue, May 12, 2009 at 3:53 PM, Skipper Seabold <jsseabold@gmail.com> wrote:
> I've been going through scipy.stats.mstats and the tests to get a
> better feel for masked arrays and how they are handled for statistical
> functions.  I noticed what I believed to be an error in the examples
> of the docstring for mstats_basic.count_tied_groups, which I corrected
> here: <http://docs.scipy.org/scipy/docs/scipy.stats.mstats_basic.count_tied_groups/>.
>
> My question is (as you can see) I had to also correct some formatting
> (and there is still some to be done), but I don't think I should be
> doing this kind of thing incrementally.  Or should I?  Is there
> another way I can edit multiple docstrings to get them to conform to
> the numpy standard and rst when I notice something or is this best
> left to someone else?  I see that mstats_basic "Needs Editing."  Sorry
> if I'm missing something obvious.  This wouldn't be the first
> time...today.
>
> Cheers,
>
> Skipper

I think any edit and improvement to the docs is good. Often when I
check the help and I find a mistake, I just correct it, without fully
editing, and reviewing the doc string. I usually just fix additionally
the main formatting errors.

If OK to apply: is "No", then the changes won't go into the source in
svn immediately, and incremental changes accumulate.

Note, in the example you could also remove the >>>  in the output
lines, and additionally any extra functions are supposed to be
imported in the doc string, eg. ma, and masked wasn't defined.

>>> count_tied_groups(z)
{2: 1, 3: 2}
>>> import numpy.ma as ma
>>> z = ma.array([0, 0, 1, 2, 2, 2, 3, 3, 4, 5, 6])
>>> z[[1,-1]] = ma.masked
>>> count_tied_groups(z, use_missing=True)
{2: 2, 3: 1}

You could correct any these basic formatting problems to get them
closer to the numpy standard.
If you find something suspicious, and you don't have time to figure it
out, you can also just add a comment.

Josef


More information about the Scipy-dev mailing list