Autosummary with toctree not creating documentation for methods

Question

I'm using sphinx with the numpydoc extension and autosummary. After some experimentation, I added the following options to my conf.py file.

autosummary_generate = True
numpydoc_show_class_members = False

This is giving me a new file for each class referenced like below, and it also creates a summary table of all of the attributes and methods.

.. autosummary::
   :toctree: generated/
   :nosignatures:

   MyClass

The problem is that while there is a summary table of the methods with the first line of the doc string, the names of the methods don't link to anything. How do I get the doc strings of the methods to also create files of their own (or at least generate the documentation in the same file as the class)?

Chickenhearted

1) Is it just that there are no links, or are the files that are supposed to be the link targets missing? 2) Instead of a summary table of the methods, I would expect to see a summary table of the classes listed in the autosummary directive. Am I misunderstanding something? – Cankerous

It's generating a file for MyClass which has an autoclass directive in it with all of the attributes and methods, but that's where it ends. The resulting HTML file contains the class doc string and summary tables of attributes and methods, but no documentation is generated for those methods. It almost seems like there needs to be another :toctree: in that file to generate the full tree. – Chickenhearted

Ok, that does help. I used autodoc_default_flags = ['members', 'undoc-members', 'show-inheritance', 'inherited-members'] in my conf.py and I'm much closer to what I need. So I'm thinking that if I want to just use generated documentation for a class, I can use autosummary with a toctree and it will put all of the documentation in a single file. However, if I want to split the method documentation out into separate files for a big class, then I would have to create a class rst file manually with an autosummary directive and have it generate the stub files for the methods, correct? – Chickenhearted

I just noticed that Pandas does it that way. They have an api.rst that is hand-written and references the class methods explicitly. They then use :toctree: to create the stubs. – Chickenhearted

I'm facing the same problem. Sphinx created a rst file for MyClass in the "generated" folder and that's it. There is no rst files for the methods. I also used autodoc_default_flags = ['members', 'undoc-members', 'show-inheritance', 'inherited-members'] but nothing changed. Did you somehow solve the problem or did you follow Pandas strategy? If you solved the problem then can you post the answer below? Many thanks. – Recluse

Answer 1

It appears that a template is needed to have sphinx generate rst files for the methods. Under _templates/autosummary I added a file named class.rst which looks like this and everything works.

Maupin

Answer 2

First, make sure that in your conf.py file, the strings 'sphinx.ext.autodoc' and 'sphinx.ext.autosummary' are in the extensions list.

Second, you can either manually make the file with name mymodule.MyClass.rst inside the generate/ directory, which can be something like this:

mymodule.MyClass
================

.. currentmodule:: mymodule

.. autoclass:: MyClass

or, if you have a lot of classes, you can automate it using sphinx-autogen. You can run it from terminal (with cd same as the conf.py file) as :

sphinx-autogen *.rst

Driedup