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

[Pauli Virtanen]

Mon, 22 Jun 2009 09:42:21 +0200, Stéfan van der Walt kirjoitti:
>
> 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.

IMHO, it would be clearer if the __init__ method was documented 
separately. It can be included on the same page in the Sphinx output as 
the class quite easily. This would allow separate referring to the class 
constructor via eg. :ref:`ndarray <ndarray.__init__>` which might result 
to cleaner documentation.

This may require some changes to the doc editor, too. I guess currently 
__init__ is not available there.

In addition to clarifying these guidelines, I think someone (me?) needs 
to spend some time on making Sphinx generate acceptable documentation for 
classes. Right now, I'd suppose that what needs to be done is 
automatically transforming the "Attributes" and "Methods" sections to 
(autosummary?) tables and placing them to the bottom of the class 
documentation pages.

We may have to implement some custom pre-generation for this, or write 
the corresponding RST files by hand. I'm not sure it's possible to do the 
above via docstring mangling. The question is mainly whether Sphinx 
tolerates toctree nodes inside class nodes. In the manual alternative, we 
write RST files for each class manually,

	.. currentmodule:: numpy

	.. autoclass:: ndarray

	   .. automethod:: __init__

	Methods
	-------

	.. autosummary::
	   :toctree:

	   ~ndarray.sum
	   ~ndarray.prod

	Attributes
	----------

	.. autosummary::
	   :toctree:

	   ~ndarray.T
	   ~ndarray.flags

or just have the Makefile pre-generate these files for us. This would be 
simpler than mucking with docutils toctrees.

One technical question here is also where the method and attribute pages 
should go in the Sphinx toctree. This has relevance for the PDF output. 
The optimal approach here seems to be the one shown above, ie., make the 
autosummary directives to be generated from the class docstrings to 
be :toctree:-ful. The method and attribute descriptions would then 
immediately follow the class description. This requires some changes to 
the workings of the stub page generation (ie. it should call the 
docstring mangling hooks also when generating), but I guess there is 
still get these changes included in Sphinx 1.0.

The intent of the Methods and Attributes sections in the above scenario 
would mostly be listing the class members that form the API. Descriptions 
given in the Methods and Attributes sections would be ignored in the 
final documentation -- at least for those members that have their own 
docstrings. I wonder if we should allow "See Also"-styled abbreviated 
description lists in these sections?

> 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.

We mostly are: WHITESPACE skipping is enabled by default in the doctests, 
so using <BLANKLINE> is never necessary -- just omit the empty line.

I'm not so sure about #doctest: +SKIP lines.

>  	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.

This probably is clarified by giving examples.

>  	419	Documenting constants
> 
> To which constants are you referring?  Give an example to clarify.

numpy.nan, numpy.inf, numpy.PZERO, numpy.e. Currently, the docstrings for 
these live in numpy.doc.constants. Not yet included in the Sphinx-
generated docs, though.

-- 
Pauli Virtanen