Doc-day will start tomorrow (in about 12 hours). It will be Friday for much of America and be moving into Saturday for Europe and Asia. Join in on the irc.freenode.net (channel scipy) to coordinate effort. I imaging people will be in an out. I plan on being available in IRC from about 9:30 am CST to 6:00 pm CST and then possibly later. If you are available at different times in different parts of the world, jump in and pick something to work on. Jarrod and/or I will put out a list of priorities in the next few hours. -Travis O.
On Dec 27, 2007 7:42 PM, Travis E. Oliphant <oliphant@enthought.com> wrote:
Doc-day will start tomorrow (in about 12 hours). It will be Friday for much of America and be moving into Saturday for Europe and Asia. Join in on the irc.freenode.net (channel scipy) to coordinate effort. I imaging people will be in an out. I plan on being available in IRC from about 9:30 am CST to 6:00 pm CST and then possibly later.
If you are available at different times in different parts of the world, jump in and pick something to work on.
Since this is our first doc-day, it will be fairly informal. Travis is going to be trying to get some estimate of which packages need the most work. But if there is some area of NumPy or SciPy you are familiar with, please go ahead and pitch in. Here is the current NumPy/ SciPy coding standard including docstring standards: http://projects.scipy.org/scipy/numpy/wiki/CodingStyleGuidelines I will be working on making the roadmaps more detailed and better documenting the discussions from the coding sprint. Travis O. will be mostly working on NumPy docstrings and possibly deprecation warnings for scipy.io functions. Matthew B. will be working on converting SciPy tests to use nose per Fernando's email. If you are familiar with nose and want to help, please make sure to check with Matthew or Fernando first. I hope to see several of you on IRC tomorrow. Happy holidays, -- Jarrod Millman Computational Infrastructure for Research Labs 10 Giannini Hall, UC Berkeley phone: 510.643.4014 http://cirl.berkeley.edu/
On Dec 27, 2007 10:27 PM, Jarrod Millman <millman@berkeley.edu> wrote:
Since this is our first doc-day, it will be fairly informal. Travis is going to be trying to get some estimate of which packages need the most work. But if there is some area of NumPy or SciPy you are familiar with, please go ahead and pitch in. Here is the current NumPy/ SciPy coding standard including docstring standards: http://projects.scipy.org/scipy/numpy/wiki/CodingStyleGuidelines
Care to make the Example section mandatory, instead of optional? I really think it should be mandatory. We may not do a good job of it initially, but at least we should express that it's of critical importance that every function contains at least one small example, whenever feasible. I also think that the above wiki page should have a minimal, self-contained example of a proper docstring with all 8 sections implemented. I'm honestly not sure at this point what the actual changes to epydoc are (in ipython we use regular epydoc with reST), and I think for many it would be much easier to get started by reading a small example rather than trying to abstract out what the exact markup should be from reading the description and the various documents linked to (doctest, reST, epydoc...). With such a guiding example, tomorrow people will be able to get up and going quickly...
I will be working on making the roadmaps more detailed and better documenting the discussions from the coding sprint.
Travis O. will be mostly working on NumPy docstrings and possibly deprecation warnings for scipy.io functions.
Matthew B. will be working on converting SciPy tests to use nose per Fernando's email. If you are familiar with nose and want to help, please make sure to check with Matthew or Fernando first.
I'm afraid I won't be able to participate tomorrow, but one thing to remember is that with nose, any and all doctest examples should be automatically picked up (with the appropriate flags). So a *very easy* way for anyone to contribute is to simply add doctest examples to the codebase. Those serve automatically two purposes: they are small tests for each function, and they make the library vastly easier to use, since any function is just one foo? away from an example. As a reminder, those of you using ipython >= 0.8.2 can use this feature: In [1]: %doctest_mode *** Pasting of code with ">>>" or "..." has been enabled. Exception reporting mode: Plain Doctest mode is: ON
for i in range(10): ... print i, ... 0 1 2 3 4 5 6 7 8 9
for i in range(10): ... ... print i, ... 0 1 2 3 4 5 6 7 8 9
%doctest_mode Exception reporting mode: Context Doctest mode is: OFF
######## The %doctest_mode magic switches the ipython prompt to >>> so you can continue using ipython but get the proper prompts for making pasteable docstests, and it also allows you to paste input that begins with '>>>' for execution, so you can try your doctests again. HTH, f
On Dec 27, 2007 9:41 PM, Fernando Perez <fperez.net@gmail.com> wrote:
Care to make the Example section mandatory, instead of optional? I really think it should be mandatory. We may not do a good job of it initially, but at least we should express that it's of critical importance that every function contains at least one small example, whenever feasible.
+1
I also think that the above wiki page should have a minimal, self-contained example of a proper docstring with all 8 sections implemented. I'm honestly not sure at this point what the actual changes to epydoc are (in ipython we use regular epydoc with reST), and I think for many it would be much easier to get started by reading a small example rather than trying to abstract out what the exact markup should be from reading the description and the various documents linked to (doctest, reST, epydoc...).
I think we already have that. Take a look at the example at the bottom: http://projects.scipy.org/scipy/numpy/wiki/CodingStyleGuidelines#example It points to a plain text example: http://svn.scipy.org/svn/numpy/trunk/numpy/doc/example.py and what it looks like rendered: http://www.scipy.org/doc/example It also explains how to check the example code out of svn and generate the html using epydoc. -- Jarrod Millman Computational Infrastructure for Research Labs 10 Giannini Hall, UC Berkeley phone: 510.643.4014 http://cirl.berkeley.edu/
On Dec 27, 2007 10:50 PM, Jarrod Millman <millman@berkeley.edu> wrote:
I also think that the above wiki page should have a minimal, self-contained example of a proper docstring with all 8 sections implemented. I'm honestly not sure at this point what the actual changes to epydoc are (in ipython we use regular epydoc with reST), and I think for many it would be much easier to get started by reading a small example rather than trying to abstract out what the exact markup should be from reading the description and the various documents linked to (doctest, reST, epydoc...).
I think we already have that. Take a look at the example at the bottom: http://projects.scipy.org/scipy/numpy/wiki/CodingStyleGuidelines#example
Oops, sorry. I read the page quickly and my brain was scanning for a big block of text in {{{ }}}, so I didn't look at that section carefully enough. My mistake. Cheers, f
Since I won't be able to participate tomorrow, here's a small contribution. I just added this to ipython: http://projects.scipy.org/ipython/ipython/browser/ipython/trunk/IPython/dtut... You can load it in your startup file or interactively via from IPython.dtutils import idoctest Type idoctest? for calling details. This will enable you to do things like: In [96]: idoctest -------> idoctest() # at this point, you start typing/pasting your doctest. Hit Ctrl-D or two blanks to end: >>> for i in range(10): ... print i, ... 0 1 2 3 4 5 6 7 8 9 1 items passed all tests: 1 tests in interactive doctest 1 tests in 1 items. 1 passed and 0 failed. Test passed. If you have a failing doctest that you'd like to debug, you can use 'eraise=True' and errors will be immediately raised, so you can then call %debug to debug them. This should come in handy for all those doctests that you're all going to write tomorrow. If you aren't running off SVN ipython, you can simply copy the above file somewhere and load it interactively once ipython is running, it doesn't depend on any other changes to ipython. It probably still needs a bit of work to make it more convenient, so I'm open to feedback. But it should make life easier when writing frequent doctests. Cheers, f
On Thu, Dec 27, 2007 at 10:41:17PM -0700, Fernando Perez wrote:
I'm afraid I won't be able to participate tomorrow, but one thing to remember is that with nose, any and all doctest examples should be automatically picked up (with the appropriate flags). So a *very easy* way for anyone to contribute is to simply add doctest examples to the codebase. Those serve automatically two purposes: they are small tests for each function, and they make the library vastly easier to use
I am not familiar with the nosetest machinery, but may I suggest that numpy is made available to doctests as 'N' or 'np'? As an example I attach a hackish script I use to excercise all the doctests in numpy. Cheers Stéfan
participants (4)
-
Fernando Perez -
Jarrod Millman -
Stefan van der Walt -
Travis E. Oliphant