[SciPy-Dev] Scipy Docs permissions

[josef.pktd at gmail.com]

On Mon, May 28, 2012 at 3:17 PM, Ralf Gommers
<ralf.gommers at googlemail.com> wrote:
> 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.

just as extra info:

    Review status: Unimportant
often means there is some reason that the docstring shouldn't be edited.

For example, in scipy.stats.distributions those docstrings are
autogenerated and they shouldn't be changed in the doceditor. (there
is a template code that can be edited.)

Josef

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