[SciPy-Dev] Scipy Docs permissions

[Ralf Gommers]

Hi Karmel,

On Mon, May 28, 2012 at 8:53 PM, Karmel Allison <karmel at arcaio.com> wrote:

> Thanks!
>
> As I begin to poke around, it occurs to me that there are many docs marked
> "Needs editing," but it's a little unclear what exactly makes a particular
> doc still in need of editing, as opposed to review. For example, for docs
> like
>

You're right that many docstrings are actually pretty good, but simply
haven't been marked as "needs review" in the doc editor. For the numpy docs
this was done, but some parts of scipy haven't been touched much in the
wiki yet.


>
> http://docs.scipy.org/scipy/docs/scipy.stats.stats.fisher_exact/ and
>
this one looks ready for review.


> http://docs.scipy.org/scipy/docs/scipy.linalg.basic.solveh_banded/
>
this one misses an example, the reST formatting is not right (for example
the line "ab[u + i - j, j] ..." should be marked green in the rendered
version) and the parameter/return types are incorrect  (boolean --> bool,
array --> ndarray).

>
> what should be improved on? Or are those just cases that haven't been
> marked "Needs review"?
>
> Similarly, for docs like
>
> http://docs.scipy.org/scipy/docs/scipy.linalg.decomp.eigh/ and
>
similar, example and formatting.


> http://docs.scipy.org/scipy/docs/scipy.cluster.vq.sqrt/
>
here you caught an imperfection in the wiki software. sqrt is a numpy
function and shouldn't show up at all here.

>
> is it the case that fixing the errors would qualify them for being ready
> for review? Or is there more on top of that you would like to see done?
>
> To generalize, then: how do you know when a particular doc is done baking?
>

The most important thing that's often missing in docstrings is a clear
usage example. When that exists, the formatting is OK and the descriptions
are clear, it is ready for review.

Some functions could also benefit from a reference and/or notes that
explain details of the algorithm or background. Whether that's appropriate
or not - and what level of detail - is a bit up to your own good judgment.

Thanks for helping out,
Ralf


> Thanks,
> Karmel
>
> On May 26, 2012, at 12:15 AM, Stéfan van der Walt wrote:
>
> > Hi Karmel
> >
> > On Fri, May 25, 2012 at 9:03 PM, Karmel Allison <karmel at arcaio.com>
> wrote:
> >> After many years of my living off the work you do, I thought I'd start
> helping out. Can I get edit permissions for the docs to start? I just
> registered with the username karmel.
> >
> > Thank you for helping out!  You now have editing permissions.
> >
> > Stéfan
> > _______________________________________________
> > 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
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/scipy-dev/attachments/20120528/0b42e1ec/attachment.html>