Add internal link checking to sphinx-build

[stephprince]

Motivation

Fix #1731.

Running sphinx-build in nitpicky mode can be used to check internal links. This PR will update the GitHub workflow / Makefile to use nitpicky mode and fix broken links/references.

A couple of notes

• Fixing all internal links will also require updates to hdmf (See related PR Fix internal links in docs hdmf-dev/hdmf#1031)

• Running sphinx-build in nitpicky mode will generate warnings by default. If we want to be stricter, we can add the -W flag to generate errors for broken internal links

• colons in docstrings get picked up by sphinx as references due to the sphinx Napoleon extension (See issue here). For now, I replaced colons with dashes, but there are a couple options for getting colons to work if it's preferred to keep them. See the image below for examples of what they might look like:
  

• Using type hints with h5py data types causes internal reference warnings. I couldn't figure out the best way to approach fixing that currently. It only happened in the get_nwbfile_version function so I switched it to use docval instead

How to test the behavior?

cd docs
make linkcheck

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.

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Comparison is base (047c37d) 92.18% compared to head (dc74e36) 92.19%.

Additional details and impacted files

@@           Coverage Diff           @@
##              dev    #1827   +/-   ##
=======================================
  Coverage   92.18%   92.19%           
=======================================
  Files          27       27           
  Lines        2637     2639    +2     
  Branches      689      690    +1     
=======================================
+ Hits         2431     2433    +2     
  Misses        136      136           
  Partials       70       70           

Flag	Coverage Δ
integration	71.35% <100.00%> (+0.02%)	⬆️
unit	84.31% <100.00%> (+0.01%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

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

[oruebel]

• For now, I replaced colons with dashes

I think that's fine.

[oruebel]

Thanks for all these fixes. Aside from the issue with the mpi Intracom in docval this looks good to me.

[rly]

That's a lot of fixes! Thank you.

[oruebel]

This looks all good to me. I would wait for @rly to approve as well, but I believe I need to approve too since I requested changes earlier.

[stephprince]

did we want to raise nitpicky warnings as errors in the workflow here too?

[rly]

did we want to raise nitpicky warnings as errors in the workflow here too?

Yes, that would be great.

It's too bad that the type hint for h5py.File doesn't play nicely with sphinx

[rly]

Looks good to me. To be clear, the remaining warning will be fixed in the next release of HDMF, right?

/home/runner/work/pynwb/pynwb/src/pynwb/__init__.py:docstring of pynwb.docval.<locals>.dec.<locals>.func_call:9:py:class reference target not found: File

[rly]

If so, let's hold off on merging until that's released.

[stephprince]

Yes the remaining warnings should be fixed in the next release of HDMF. Right now it's stopping at the first warning (there are a lot more). If we want to show the rest of the errors in the workflow run we could add the --keep-going flag.

[rly]

@stephprince It looks like there is a new failure in the build - could you please look into it today if you can? If not, let me know and I'll try. I would like this in the next pynwb release today/tomorrow.