Setup sphinx.ext.autosummary for the API-docs

[oruebel]

Motivation

Evaluate the use of sphinx.ext.autosummary to enhance the navigation of the API docs. See also:

https://github.com/hdmf-dev/hdmf/issues/653

Checklist

• [ ] Did you update CHANGELOG.md with your changes?
• [X] Have you checked our Contributing document?
• [X] Have you ensured the PR clearly describes the problem and the solution?
• [X] Is your contribution compliant with our coding style? This can be checked running flake8 from the source directory.
• [X] Have you checked to ensure that there aren't other open Pull Requests for the same change?
• [X] Have you included the relevant issue number using "Fix #XXX" notation where XXX is the issue number? By including "Fix #XXX" you allow GitHub to close issue #XXX when the PR is merged.

[oruebel]

@rly if you get a chance, can you build the docs for this PR and see how the new summary and navigation for the API docs look. This PR is basically ready.

There is one remaining issue in that I am getting a lot of warnings while building the docs of the form:

WARNING: duplicate object description of hdmf.XXXX, other instance in _autosummary/hdmf.XXXXX, use :noindex: for one of them

I'm not sure yet how to fix these. The docs seem to work fine but it would be best to fix these before merging. Any idea how to best fix these?

[rly]

This looks like a good start to me. I was able to remove the warnings by editing the autosummary template and adding :noindex: under automodule. I agree that there are a few kinks to be worked out, e.g., links from the autogenerated tables point to different pages than the links in the navigation bar.

[oruebel]

@rly what do you think are the main open items we should resolve before merging this? Its fine to leave this PR open for a future docathon but it would be useful to mark what areas we would like to further improve on this to allow folks to chip in.

[rly]

1. fix the reference links and breadcrumb links so that they consistently go to the autosummary nicer pages. remove the other pages if possible.
2. fix warnings:

      C:\Users\Ryan\Documents\NWB\hdmf\src\hdmf\common\table.py:docstring of hdmf.common.table.VectorData.get:4: WARNING: Inline strong start-string without end-string.
      C:\Users\Ryan\Documents\NWB\hdmf\docs\source\tutorials\External_Resources.rst:53: WARNING: Unexpected indentation.
      C:\Users\Ryan\Documents\NWB\hdmf\docs\source\tutorials\External_Resources.rst:54: WARNING: Block quote ends without a blank line; unexpected unindent.
      looking for now-outdated files... none found
      pickling environment... done
      checking consistency... C:\Users\Ryan\Documents\NWB\hdmf\docs\source\getting_started.rst: WARNING: document isn't C:\Users\Ryan\Documents\NWB\hdmf\docs\source\hdmf.rst: WARNING: document isn't included in any toctree
   

3. add docstrings to the functions and classes missing docstrings
4. in the left sidebar, remove the TOC for hdmf that just lists modules, both at the root level and under Data API
5. see if there is a way to have the appropriate TOC sidebar expanded when viewing a class or module

[codecov[bot]]

Codecov Report

Attention: Patch coverage is 50.00000% with 1 lines in your changes are missing coverage. Please review.

Project coverage is 87.37%. Comparing base (6d0be17) to head (c6f2cda).

:exclamation: Current head c6f2cda differs from pull request most recent head 52ef49a. Consider uploading reports for the commit 52ef49a to get more accurate results

Files	Patch %	Lines
src/hdmf/__init__.py	0.00%	1 Missing :warning:

Additional details and impacted files

@@            Coverage Diff             @@
##              dev     #654      +/-   ##
==========================================
- Coverage   88.70%   87.37%   -1.33%     
==========================================
  Files          45       44       -1     
  Lines        9745     8730    -1015     
  Branches     2767     2007     -760     
==========================================
- Hits         8644     7628    -1016     
- Misses        779      787       +8     
+ Partials      322      315       -7     

:umbrella: View full report in Codecov by Sentry.
:loudspeaker: Have feedback on the report? Share it here.