Hi all, 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. Thanks! Karmel
Hi Karmel On Fri, May 25, 2012 at 9:03 PM, Karmel Allison <karmel@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
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 http://docs.scipy.org/scipy/docs/scipy.stats.stats.fisher_exact/ and http://docs.scipy.org/scipy/docs/scipy.linalg.basic.solveh_banded/ 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 http://docs.scipy.org/scipy/docs/scipy.cluster.vq.sqrt/ 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? 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@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@scipy.org http://mail.scipy.org/mailman/listinfo/scipy-dev
Hi Karmel, On Mon, May 28, 2012 at 8:53 PM, Karmel Allison <karmel@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.
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@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@scipy.org http://mail.scipy.org/mailman/listinfo/scipy-dev
_______________________________________________ SciPy-Dev mailing list SciPy-Dev@scipy.org http://mail.scipy.org/mailman/listinfo/scipy-dev
On Mon, May 28, 2012 at 3:17 PM, Ralf Gommers <ralf.gommers@googlemail.com> wrote:
Hi Karmel,
On Mon, May 28, 2012 at 8:53 PM, Karmel Allison <karmel@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.
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@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@scipy.org http://mail.scipy.org/mailman/listinfo/scipy-dev
_______________________________________________ SciPy-Dev mailing list SciPy-Dev@scipy.org http://mail.scipy.org/mailman/listinfo/scipy-dev
_______________________________________________ SciPy-Dev mailing list SciPy-Dev@scipy.org http://mail.scipy.org/mailman/listinfo/scipy-dev
That all helps clarify. Thanks! On May 28, 2012, at 12:17 PM, Ralf Gommers wrote:
Hi Karmel,
On Mon, May 28, 2012 at 8:53 PM, Karmel Allison <karmel@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@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@scipy.org http://mail.scipy.org/mailman/listinfo/scipy-dev
_______________________________________________ SciPy-Dev mailing list SciPy-Dev@scipy.org http://mail.scipy.org/mailman/listinfo/scipy-dev
_______________________________________________ SciPy-Dev mailing list SciPy-Dev@scipy.org http://mail.scipy.org/mailman/listinfo/scipy-dev
On Mon, May 28, 2012 at 2:53 PM, Karmel Allison <karmel@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
http://docs.scipy.org/scipy/docs/scipy.stats.stats.fisher_exact/ and http://docs.scipy.org/scipy/docs/scipy.linalg.basic.solveh_banded/
what should be improved on? Or are those just cases that haven't been marked "Needs review"?
Mostly the later I think. Some functions like fisher_exact get good docstrings during a commit, and nobody updates the label in the editor. for stats, I went through many of them some time ago to change labels, but I just found that fisher_exact is missing from the milestone http://docs.scipy.org/scipy/Milestones/Milestones_11/ which I had used as basis for relabeling. examples if they don't require a huge program would be nice to make a docstring complete, link to tutorial, if available, would also be good Josef
Similarly, for docs like
http://docs.scipy.org/scipy/docs/scipy.linalg.decomp.eigh/ and http://docs.scipy.org/scipy/docs/scipy.cluster.vq.sqrt/
what is sqrt doing in 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?
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@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@scipy.org http://mail.scipy.org/mailman/listinfo/scipy-dev
_______________________________________________ SciPy-Dev mailing list SciPy-Dev@scipy.org http://mail.scipy.org/mailman/listinfo/scipy-dev
participants (4)
-
josef.pktd＠gmail.com -
Karmel Allison -
Ralf Gommers -
Stéfan van der Walt