[Numpy-discussion] something wrong with docs?

[David Goldsmith]

On Mon, Sep 21, 2009 at 6:49 PM, Fernando Perez <fperez.net at gmail.com>wrote:

> On Mon, Sep 21, 2009 at 11:32 AM, Pauli Virtanen <pav at iki.fi> wrote:
> > The `sphinx.ext.doctest` extension is not enabled, so the testcode::
> > etc. directives are not available. I'm not sure if it should be enabled
> > -- it would be cleaner to just replace the testcode:: stuff with the
> > ordinary example markup.
> >
>
> Why not enable it?  It would be nice if we could move gradually
> towards docs whose examples (at least those marked as such) were
> always run via sphinx.  The more we do this, the higher the chances of
>

Later in this thread, Fernando, you make a good case - scalability - for
this, which, as someone who's been using only >>>, raises a number of
questions in my mind: 0) this isn't applicable to docstrings, only to
numpy-docs (i.e., the .rst files), correct; 1) assuming the answer is "yes,"
is there a "standard" for these ala the docstring standard, or some other
extant way to promulgate and "strengthen" your "suggestion" (after proper
community vetting, of course); 2) for those of us new to this approach, is
there a "standard example" somewhere we can easily reference?  Thanks!

DG

non-zero overlap between documentation and reality :)
>
> Cheers,
>
> f
> _______________________________________________
> NumPy-Discussion mailing list
> NumPy-Discussion at scipy.org
> http://mail.scipy.org/mailman/listinfo/numpy-discussion
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/numpy-discussion/attachments/20090922/b2daa634/attachment.html>