[SciPy-dev] Doc-ing classes and data attributes

[Ralf Gommers]

On Mon, Jun 22, 2009 at 3:03 PM, Ralf Gommers
<ralf.gommers at googlemail.com>wrote:

>
>
> 2009/6/22 Stéfan van der Walt <stefan at sun.ac.za>
>
>> Hi Ralf
>>
>> Thanks for the patch!  I committed your fixes up to the point where
>> you start discussing class documentation.
>>
>> We have to decide: is it OK to document the class constructor in
>> __init__?  We used to put this in the class docstring itself so that
>> "help" and IPython's "?" would find it, but I don't think this is
>> longer necessary.  On the other hand, it makes sense: you call "x =
>> MyClass()" to construct, not "x = MyClass.__init__()".  Comments
>> welcome.
>>
>> A couple of questions and comments about the patch:
>>
>>        326        Not all examples will run though, due to them including
>> blank lines
>>        327        in the output. Do not put in doctest-specific markup
>> like
>>        328        ``<BLANKLINE>`` or ``#doctest: +SKIP``, readability is
>> more important
>>        329        here than being able to execute the doctests in a
>> testing framework.
>>
>> What is the plan here?  We must be able to execute the doctests in some
>> way.
>>
>
> From previous emails on the list (from Robert) I learned that we do not
> execute these doctests, and do not even have a way of doing that at the
> moment. If that's not correct then the ``#doctest: +SKIP`` should stay. If
> it is correct, then doctest directives are just noise that the user should
> not see.
>


Okay, I tried running doctests. I chose polynomial.py as an example.
Executing:
$ nosetests --with-doctest numpy/lib/polynomial.py
first gives all errors, because ``import numpy as np`` is missing. Adding
that, I still get errors:

$ nosetests --with-doctest numpy/lib/polynomial.py
.F.F/usr/lib/python2.6/dist-packages/matplotlib/texmanager.py:55:
DeprecationWarning: os.popen4 is deprecated.  Use the subprocess
module.

  stdin, stdout = os.popen4('dvipng
-version')

FF...


======================================================================
FAIL: Doctest: numpy.lib.polynomial.polydiv
----------------------------------------------------------------------
Traceback (most recent call last):
  File "/usr/lib/python2.6/doctest.py", line 2145, in runTest
    raise self.failureException(self.format_failure(new.getvalue()))
AssertionError: Failed doctest test for numpy.lib.polynomial.polydiv
  File "/home/ralf/python/numpy/numpy/lib/polynomial.py", line 680, in
polydiv

----------------------------------------------------------------------
File "/home/ralf/python/numpy/numpy/lib/polynomial.py", line 712, in
numpy.lib.polynomial.polydiv
Failed
example:

    np.polydiv(x,
y)

Expected
nothing

Got:

    (array([ 1.5 ,  1.75]), array([
0.25]))


(...lots more errors here...)


Ran 9 tests in 5.643s

FAILED (failures=4)



It looks like these doctests have not worked in a long time. There is also a
conceptual problem, do you really want everyone who signs up in the doc
editor to be able to produce test failures because they wrote an example
that doctest does not like?

It seems like removing the part about running doctests from the
documentation standard is the way to go.

Cheers,
Ralf



>
>>        409     Class instances normally take the docstring of the class.
>> In the Numpy
>>        410     namespace some class instances are made available to expose
>> certain
>>        411     functionality.
>>
>> I know what you mean by the above, but I think these sentences are a
>> bit confusing.
>>
>
> I'll rephrase and give a concrete example.
>
>
>>
>>        419     Documenting constants
>>
>> To which constants are you referring?  Give an example to clarify.
>>
>>        436     * [,out] : All ufuncs accept an optional `out` argument.
>> This is
>>        437       documented in the **Output arguments** section of
>> `doc.ufuncs`. In the
>>        438       docstring this argument should be documented like this::
>>        439
>>        440         out : ndarray, optional
>>        441             Array into which the output is placed. Its type is
>> preserved and
>>        442             it must be of the right shape to hold the output.
>> See
>> `doc.ufuncs`.
>>
>> I think we can leave this out of the standard, since it pertains to a
>> very specific part of numpy.
>
>
> Maybe it doesn't belong in the standard, but it should be somewhere so we
> get these things done as uniformly as possible. I'd be happy with a wiki
> page for points like this.
>
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/scipy-dev/attachments/20090623/e0482216/attachment.html>