Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Setup sphinx.ext.autosummary for the API-docs #654

Open
wants to merge 15 commits into
base: dev
Choose a base branch
from

Conversation

oruebel
Copy link
Contributor

@oruebel oruebel commented Jul 21, 2021

Motivation

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

#653

Checklist

  • Did you update CHANGELOG.md with your changes?
  • Have you checked our Contributing document?
  • Have you ensured the PR clearly describes the problem and the solution?
  • Is your contribution compliant with our coding style? This can be checked running flake8 from the source directory.
  • Have you checked to ensure that there aren't other open Pull Requests for the same change?
  • 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
Copy link
Contributor Author

oruebel commented Jul 23, 2021

@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
Copy link
Contributor

rly commented Jul 29, 2021

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
Copy link
Contributor Author

oruebel commented Jul 29, 2021

@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
Copy link
Contributor

rly commented Jul 29, 2021

  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

@rly rly marked this pull request as ready for review March 26, 2022 00:02
@codecov
Copy link

codecov bot commented Mar 27, 2022

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).

❗ 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 ⚠️
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     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants