[Numpy-discussion] [SciPy-dev] Doc-day

Fernando Perez fperez.net@gmail....
Thu Dec 27 23:41:17 CST 2007

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


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.



More information about the Numpy-discussion mailing list