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