[SciPy-dev] Doc-ing classes and data attributes
Stéfan van der Walt
Mon Jun 22 02:42:21 CDT 2009
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
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.
409 Class instances normally take the docstring of the class. In the Numpy
410 namespace some class instances are made available to expose certain
I know what you mean by the above, but I think these sentences are a
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::
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
I think we can leave this out of the standard, since it pertains to a
very specific part of numpy.
2009/6/22 Ralf Gommers <email@example.com>:
> 2009/6/21 Stéfan van der Walt <firstname.lastname@example.org>
>> 2009/6/21 Ralf Gommers <email@example.com>:
>> > The CodingStyleGuidelines page is generated from
>> > /trunk/doc/HOWTO_DOCUMENT.txt so editing on Trac is not what you want.
>> > The
>> > page is already in reST format, so can we add it to the doc editor and
>> > edit
>> > it there?
>> The documentation standard should not be open to editing. You are, of
>> course, welcome to provide patches that we can apply after discussion,
>> but this document cannot be in a state of flux.
> You're right that it should not be in a state of flux. I attached a patch to
> #1146 for review.
More information about the Scipy-dev