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?