Use sphinx.ext.autosummary to create better index for API docs

[oruebel]

Currently the the index for the API docs is in part defined manually and is not easy to navigate (see https://github.com/hdmf-dev/hdmf/blob/dev/docs/source/api_docs.rst and https://hdmf.readthedocs.io/en/stable/api_docs.html) It would be useful to update the docs to use the sphinx extension sphinx.ext.autosummary for this. See:

• https://www.sphinx-doc.org/en/master/usage/extensions/autosummary.html
• https://stackoverflow.com/questions/2701998/sphinx-autodoc-is-not-automatic-enough/62613202#62613202

Addressing this issue may also require adding missing docstrings for python modules to further enhance the utility of the API docs.

Checklist

• [X] Have you ensured the feature or change was not already reported ?
• [X] Have you included a brief and descriptive title?
• [X] Have you included a clear description of the problem you are trying to solve?
• [X] Have you included a minimal code snippet that reproduces the issue you are encountering?
• [X] Have you checked our Contributing document?

[oruebel]

https://github.com/hdmf-dev/hdmf/pull/654 is a start at this, but there are still a few issues that need to be worked out. E.g., links from the autogenerated tables point to different pages than the links in the navigation bar. The PR is mainly to evaluate sphinx.ext.autosummary and to provide a starting-point for other who want to help with this issue.

[mavaylon1]

@stephprince Thought this would be a good fit as a "first issue" ticket.

[oruebel]

https://github.com/hdmf-dev/hdmf/pull/654/ was a first attempt at this several years ago, but the PR wasn't pushed over the finish line. This comment in the PR https://github.com/hdmf-dev/hdmf/pull/654/#issuecomment-889512458 lists the items that still needed to be finished in the PR. I just updated the PR to resolve merge conflicts. I don't think it should be too bad to push that PR over the finish line. Happy to help during the dev days with this.