[Numpy-discussion] Autosummary using numpydoc

[Matthew Turk]

Hi there,

I've been trying to take the numpy docstring and apply the same
methodology to a different project I work on, but there are a couple
details that I think I'm unclear on, and I was hoping for some
pointers or at least reassurances that it's working as intended,
despite Sphinx's protests.

The process of applying the numpy docstring method seems to take a few steps:

0) Have sphinx >=1.0 installed.
1) Write a numpydoc-compliant docstring in a class and its methods.
2) Make available to sphinx the numpydoc extension (in this case, I am
using the current numpy git tip, which self-reports as 0.4)
3) Add the sphinx.ext.autosummary and numpydoc extensions to conf.py
in the appropriate sphinx project
4) Copy the autosummary/class.rst template to the appropriate
_template directory in the sphinx project
5) Set up the autosummary_generate variable in conf.py to contain all
the files containing autosummary directives.
6) Build docs

As a few other quick notes, my reading of the overridden class.rst
template is that it comments out the individual method inclusions,
using the HACK (comment) directive.

The build mostly proceeds correctly when these steps have been taken,
but a copious number of warnings are emitted.  (The same character of
warnings are emitted by the numpy documentation build.)  These mostly
show up, for instance, as:

WARNING: toctree contains reference to nonexisting document
'reference/api/generated/add_phase_object'

In this case, add_phase_object is a method hanging off an
autosummary'ed class.  It looks like a warning gets emitted for every
method on every autosummary'ed class -- this can number into the
thousands very easily.  Additionally, warnings that look like:

reference/api/generated/yt.visualization.api.PlotCollection.add_phase_object.rst::
WARNING: document isn't included in any toctree

show up, where these reflect the full method name and class name.  It
looks like the toctree is gaining references to the method names
without prefixing them with the class names, but the generated docs
all have the full name resolution in their filenames.  (There also
seems to be a glitch in the output when using the ".. HACK" class.rst
template, as within my code it appears to strip the one-line
descriptions from the methods.)

Is this behaving as expected, or have I perhaps gone through the steps
wrong?  Having so many warnings can confuse debugging other portions
of the build.

I appreciate any suggestions you might have -- thanks very much!

Best,

Matt