[Numpy-discussion] something wrong with docs?

[Fernando Perez]

On Tue, Sep 22, 2009 at 11:15 PM, David Goldsmith
<d.l.goldsmith at gmail.com> wrote:
> "It would be nice if we could move gradually
> towards docs whose examples (at least those marked as such) were
> always run via sphinx."
>
> That's a "suggestion," but given your point, it seems like you'd advocate it
> being more than that, no?
>

I was simply thinking that if this markup were to be used in the docs
for all examples where it makes sense, then one could simply use the
sphinx target

make doctest

to also validate the documentation.  Even if users don't run these by
default, developers and buildbots would, which helps raise the
reliability of the docs and reduces chances of code bitrot in the
examples from the main docs (that problem is taken care of for the
docstrings by np.test(doctest=True) ).

Cheers,

f