Add internal link checking to sphinx-build (#1827)

* add zarr intersphinx mapping

* fix space typos

* update links in tutorials

* add nitpicky mode to make files and workflow

* fix docstring links

* replace colons in docstrings for sphinx doc building

* fix typo in docval inputs

* update changelog

* fix code blocks from italics in tutorials

* move nitpicky configuration to conf.py file

* revert Intracomm type string

* convert italics to code blocks in tutorials

* update nitpick_ignore to include BaseStorageSpec

* raise nitpicky warnings as errors

* Use hdmf 3.12.1

* fix broken link in tutorial

---------

Co-authored-by: Ryan Ly <[email protected]>

Author: stephprince

.github/workflows/check_external_links.yml renamed to .github/workflows/check_sphinx_links.yml

@@ -1,12 +1,12 @@
-name: Check Sphinx external links
+name: Check Sphinx links
 on:
   pull_request:
   schedule:
     - cron: '0 5 * * *'  # once per day at midnight ET
   workflow_dispatch:
 
 jobs:
-  check-external-links:
+  check-sphinx-links:
     runs-on: ubuntu-latest
     steps:
       - name: Cancel non-latest runs
@@ -31,5 +31,5 @@ jobs:
           python -m pip install -r requirements-doc.txt
           python -m pip install .
 
-      - name: Check Sphinx external links
-        run: sphinx-build -b linkcheck ./docs/source ./test_build
+      - name: Check Sphinx internal and external links
+        run: sphinx-build -W -b linkcheck ./docs/source ./test_build

CHANGELOG.md

@@ -22,6 +22,7 @@
 ### Documentation and tutorial enhancements
 - Add RemFile to streaming tutorial. @bendichter [#1761](https://github.com/NeurodataWithoutBorders/pynwb/pull/1761)
 - Fix typos and improve clarify throughout tutorials. @zm711 [#1825](https://github.com/NeurodataWithoutBorders/pynwb/pull/1825)
+- Fix internal links in docstrings and tutorials. @stephprince [#1827](https://github.com/NeurodataWithoutBorders/pynwb/pull/1827)
 - Add Zarr IO tutorial @bendichter [#1834](https://github.com/NeurodataWithoutBorders/pynwb/pull/1834)
 
 ## PyNWB 2.5.0 (August 18, 2023)

docs/Makefile

@@ -149,7 +149,7 @@ changes:
 	@echo "The overview file is in $(BUILDDIR)/changes."
 
 linkcheck:
-	$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
+	$(SPHINXBUILD) -W -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
 	@echo
 	@echo "Link check complete; look for any errors in the above output " \
 	      "or in $(BUILDDIR)/linkcheck/output.txt."

docs/gallery/advanced_io/h5dataio.py

@@ -34,7 +34,7 @@
 
 
 ####################
-# Normally if we create a :py:class:`~pynwb.file.TimeSeries` we would do
+# Normally if we create a :py:class:`~pynwb.base.TimeSeries` we would do
 
 import numpy as np
 

docs/gallery/advanced_io/plot_editing.py

@@ -129,7 +129,7 @@
 # Editing groups
 # --------------
 # Editing of groups is not yet supported in PyNWB.
-# To edit the attributes of a group, open the file and edit it using :py:mod:`h5py`:
+# To edit the attributes of a group, open the file and edit it using ``h5py``:
 
 import h5py
 

docs/gallery/domain/images.py

@@ -190,7 +190,7 @@
 # ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 #
 # :py:class:`~pynwb.image.RGBAImage` is for storing data of color image with transparency.
-# :py:attr:`~pynwb.image.RGBAImage.data` must be 3D where the first and second dimensions
+# ``RGBAImage.data`` must be 3D where the first and second dimensions
 # represent x and y. The third dimension has length 4 and represents the RGBA value.
 #
 
@@ -208,7 +208,7 @@
 # ^^^^^^^^^^^^^^^^^^^^^^^^^^
 #
 # :py:class:`~pynwb.image.RGBImage` is for storing data of RGB color image.
-# :py:attr:`~pynwb.image.RGBImage.data` must be 3D where the first and second dimensions
+# ``RGBImage.data`` must be 3D where the first and second dimensions
 # represent x and y. The third dimension has length 3 and represents the RGB value.
 #
 
@@ -224,8 +224,7 @@
 # ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 #
 # :py:class:`~pynwb.image.GrayscaleImage` is for storing grayscale image data.
-# :py:attr:`~pynwb.image.GrayscaleImage.data` must be 2D where the first and second dimensions
-# represent x and y.
+# ``GrayscaleImage.data`` must be 2D where the first and second dimensions represent x and y.
 #
 
 gs_logo = GrayscaleImage(
@@ -300,7 +299,7 @@
 
 ####################
 # Here `data` contains the (0-indexed) index of the displayed image as they are ordered
-# in the :py:class:`~pynwb.base.ImageReference`.
+# in the :py:class:`~pynwb.base.ImageReferences`.
 #
 # Writing the images to an NWB File
 # ---------------------------------------

docs/gallery/domain/ophys.py

@@ -540,7 +540,7 @@
 # Data arrays are read passively from the file.
 # Calling the data attribute on a :py:class:`~pynwb.base.TimeSeries`
 # such as a :py:class:`~pynwb.ophys.RoiResponseSeries` does not read the data
-# values, but presents an :py:class:`~h5py` object that can be indexed to read data.
+# values, but presents an ``h5py`` object that can be indexed to read data.
 # You can use the ``[:]`` operator to read the entire data array into memory.
 # Load and print all the data values of the :py:class:`~pynwb.ophys.RoiResponseSeries`
 # object representing the fluorescence data.
@@ -558,7 +558,7 @@
 #
 # It is often preferable to read only a portion of the data. To do this, index
 # or slice into the data attribute just like if you were indexing or slicing a
-# :py:class:`~numpy` array.
+# :py:mod:`numpy` array.
 #
 # The following code prints elements ``0:10`` in the first dimension (time)
 # and ``0:3`` (ROIs) in the second dimension from the fluorescence data we have written.

docs/gallery/domain/plot_icephys.py

@@ -350,7 +350,7 @@
 #####################################################################
 # .. note:: Since :py:meth:`~pynwb.file.NWBFile.add_intracellular_recording` can automatically add
 #          the objects to the NWBFile we do not need to separately call
-#          :py:meth:`~pynwb.file.NWBFile.add_stimulus` and :py:meth:`~pynwb.file.NWBFile.add_acquistion`
+#          :py:meth:`~pynwb.file.NWBFile.add_stimulus` and :py:meth:`~pynwb.file.NWBFile.add_acquisition`
 #          to add our stimulus and response, but it is still fine to do so.
 #
 # .. note:: The ``id`` parameter in the call is optional and if the ``id`` is omitted then PyNWB will
@@ -495,8 +495,7 @@
 # .. note:: The same process applies to all our other tables as well. We can use the
 #         corresponding :py:meth:`~pynwb.file.NWBFile.get_intracellular_recordings`,
 #         :py:meth:`~pynwb.file.NWBFile.get_icephys_sequential_recordings`,
-#         :py:meth:`~pynwb.file.NWBFile.get_icephys_repetitions`, and
-#         :py:meth:`~pynwb.file.NWBFile.get_icephys_conditions` functions instead.
+#         :py:meth:`~pynwb.file.NWBFile.get_icephys_repetitions` functions instead.
 #         In general, we can always use the get functions instead of accessing the property
 #         of the file.
 #
@@ -507,7 +506,7 @@
 #
 # Add a single simultaneous recording consisting of a set of intracellular recordings.
 # Again, setting the id for a simultaneous recording is optional. The recordings
-# argument of the :py:meth:`~pynwb.file.NWBFile.add_simultaneous_recording` function
+# argument of the :py:meth:`~pynwb.file.NWBFile.add_icephys_simultaneous_recording` function
 # here is simply a list of ints with the indices of the corresponding rows in
 # the :py:class:`~pynwb.icephys.IntracellularRecordingsTable`
 #
@@ -564,7 +563,7 @@
 # Add a single sequential recording consisting of a set of simultaneous recordings.
 # Again, setting the id for a sequential recording is optional. Also this table is
 # optional and will be created automatically by NWBFile. The ``simultaneous_recordings``
-# argument of the :py:meth:`~pynwb.file.NWBFile.add_sequential_recording` function
+# argument of the :py:meth:`~pynwb.file.NWBFile.add_icephys_sequential_recording` function
 # here is simply a list of ints with the indices of the corresponding rows in
 # the :py:class:`~pynwb.icephys.SimultaneousRecordingsTable`.
 
@@ -579,7 +578,7 @@
 # Add a single repetition consisting of a set of sequential recordings. Again, setting
 # the id for a repetition is optional. Also this table is optional and will be created
 # automatically by NWBFile. The ``sequential_recordings argument`` of the
-# :py:meth:`~pynwb.file.NWBFile.add_sequential_recording` function here is simply
+# :py:meth:`~pynwb.file.NWBFile.add_icephys_repetition` function here is simply
 # a list of ints with the indices of the corresponding rows in
 # the :py:class:`~pynwb.icephys.SequentialRecordingsTable`.
 
@@ -592,7 +591,7 @@
 # Add a single experimental condition consisting of a set of repetitions. Again,
 # setting the id for a condition is optional. Also this table is optional and
 # will be created automatically by NWBFile. The ``repetitions`` argument of
-# the :py:meth:`~pynwb.file.NWBFile.add_icephys_condition` function again is
+# the :py:meth:`~pynwb.file.NWBFile.add_icephys_experimental_condition` function again is
 # simply a list of ints with the indices of the correspondingto rows in the
 # :py:class:`~pynwb.icephys.RepetitionsTable`.
 

docs/gallery/general/add_remove_containers.py

@@ -78,7 +78,7 @@
 # have raw data and processed data in the same NWB file and you want to create a new NWB file with all the contents of
 # the original file except for the raw data for sharing with collaborators.
 #
-# To remove existing containers, use the :py:class:`~hdmf.utils.LabelledDict.pop` method on any
+# To remove existing containers, use the :py:meth:`~hdmf.utils.LabelledDict.pop` method on any
 # :py:class:`~hdmf.utils.LabelledDict` object, such as ``NWBFile.acquisition``, ``NWBFile.processing``,
 # ``NWBFile.analysis``, ``NWBFile.processing``, ``NWBFile.scratch``, ``NWBFile.devices``, ``NWBFile.stimulus``,
 # ``NWBFile.stimulus_template``, ``NWBFile.electrode_groups``, ``NWBFile.imaging_planes``,

docs/gallery/general/object_id.py

@@ -10,7 +10,7 @@
 unique and used widely across computing platforms as if they are unique.
 
 The object ID of an NWB container object can be accessed using the
-:py:meth:`~hdmf.container.AbstractContainer.object_id` method.
+:py:attr:`~hdmf.container.AbstractContainer.object_id` method.
 
 .. _UUID: https://en.wikipedia.org/wiki/Universally_unique_identifier