I have looked into the rendering of the matplotlib modules in the documentations. The goal should be to have:

• easy to read documentation.
• easy to get an overview of classes and functions.
• easy to find related examples and tutorials.
• limit manual work.

I would say that some modules, like the the axes module, is well documented (but quite a lot of manual work where probably needed) but some other like the collections module is not. It is really difficult to get any sort of overview when everything is in one file without any links.

I have tried some different solutions:

• automodapi
  • Mostly automatic but some classes and functions that are imported needs to be taken away manually.
  • All classes on a single page but there are links to the methods.
  • Attributes are included (I am not sure if there are a option to not include them)
  • No automatic links to examples
• automodsumm
  • should work as automodsummary but it doesn't at the moment but maybe later.
  • The templates below should result in the same result with automodsumm
• autosummary with templates, one file
  • The result is similar to automodapi
  • Same manual work is needed on the first page with an autosummary
    • most of the time easy with a simple script or using dir.
  • Links to examples are included.
    • sometimes the same examples appear several times... (with the actual implementation)
  • Links make it possibly to get an overview
  • One file make it easier to skim through many docstrings fast
  • Probably good for relative small classes
• autosummary with templates, many files
  • Some manual work needed on the first page
  • Good overview
  • Might result in many clicks when looking through a class
  • links to examples included
  • The documentation probably takes much longer to build

The code can be found in #11595

Some questions:

• What is best?
  • Many pages?
  • A single page for a class?
• Should attributes be included in the documentation?
• Should inherited members always be included?
  • I guess so but this result in same methods being documentated many times and might clutter the
    more important methods for some classes.
• Automatic vs manual work?
• Should the signature be included in the autosummary lists?

Some discussion in #11572