BUG: numpy needs to override the sphinx autosummary class.rst

[mattip]

I am not sure of the interactions between all the pieces, but here my understanding:

• numpy has a class.rst template that extends the one in sphinx's autosummary extension. It adds a toctree option to a nested autosummary directive (nested under a HACK directive)
• During the parse phase, sphinx adds the toctree contents to the documentation, since this is all done with regex and it doesn't care there are nested directives
• Since sphinx ignores nested directives during output processing, the toctree is not generated
• As far as sphinx is concerned, the generated documents are not in any toctree, so we added an orphan tag to them in additional templates in numpy to avoid a warning.

So why do we need the toctree in the template in the first place? Removing the numpy class.rst seems to produce problematic documentation. Is this a numpydoc or sphinx problem or just a feature?

[larsoner]

I recently did some work to remove all warnings from the SciPy docs so that we could run in strict warnings-as-errors mode (-nWT --keep-going). We have what sounds like similar class.rst stuff, and the places we have :orphan: are in the attribute.rst and method.rst templates (probably related to your last bullet). So for the sake of discussion I'm going to assume NumPy and SciPy are trying to do the same things here. And if you want to also try being more pedantic about doc building (if you aren't already), you could try adopting the templates and options added in the PR referenced above.

why do we need the toctree in the template in the first place?

Removing the :toctree: lines in the SciPy class.rst template yields a ton of warnings about missing links, and the methods pages for classes are not generated. Based on the autosummary docs I guess this is because, without the :toctree:, the stubs for the methods for classes are not generated.

Is this a numpydoc or sphinx problem or just a feature?

I think it's a consequence of how the docs are designed to be built, namely with methods documented on pages that are separate from those of the class itself, e.g.:

https://docs.scipy.org/doc/scipy/reference/generated/scipy.interpolate.interp1d.html
https://docs.scipy.org/doc/scipy/reference/generated/scipy.interpolate.interp1d.__call__.html

I have another package where we do want the methods documented on the same page as the class itself (or at least don't mind it):

http://mne-tools.github.io/dev/generated/mne.SourceEstimate.html

We don't have to do any of this autosummary tweaking in our class.rst.