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

[Jarrod Millman]

On Dec 27, 2007 9:41 PM, Fernando Perez <fperez.net at 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/