On Dec 27, 2007 10:27 PM, Jarrod Millman <[EMAIL PROTECTED]> 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 _______________________________________________ Numpy-discussion mailing list Numpy-discussion@scipy.org http://projects.scipy.org/mailman/listinfo/numpy-discussion
