[Numpy-discussion] [SciPy-dev] Doc-day
Thu Dec 27 23:41:17 CST 2007
On Dec 27, 2007 10:27 PM, Jarrod Millman <firstname.lastname@example.org> 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:
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,
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
away from an example. As a reminder, those of you using ipython >=
0.8.2 can use this feature:
In : %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
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.
More information about the Numpy-discussion