Add link check workflow and fix broken links (#562)

* fix broken links * update make to use nitpicky mode for linkcheck * add github workflow for sphinx link checks * update sphinx linkcheck workflow * update installation step of workflow --------- Co-authored-by: Ryan Ly <[email protected]>
NeurodataWithoutBorders · Dec 19, 2023 · 6ce41fa · 6ce41fa
1 parent a8df775
commit 6ce41fa
Show file tree

Hide file tree

Showing 7 changed files with 47 additions and 11 deletions.
diff --git a/.github/workflows/check_sphinx_links.yml b/.github/workflows/check_sphinx_links.yml
@@ -0,0 +1,34 @@
+name: Check Sphinx external links and references
+on:
+  pull_request:
+  schedule:
+    - cron: '0 5 * * *'  # once per day at midnight ET
+  workflow_dispatch:
+
+jobs:
+  check-external-links:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Cancel non-latest runs
+        uses: styfle/[email protected]
+        with:
+          all_but_latest: true
+          access_token: ${{ github.token }}
+
+      - uses: actions/checkout@v4
+        with:
+          submodules: 'recursive'
+          fetch-depth: 0  # tags are required for versioneer to determine the version
+
+      - name: Set up Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: '3.12'
+
+      - name: Install Sphinx dependencies and package
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install -r requirements-doc.txt
+
+      - name: Check Sphinx links and references
+        run: sphinx-build -n -b linkcheck ./docs/format/source ./test_build
diff --git a/docs/format/Makefile b/docs/format/Makefile
@@ -159,7 +159,7 @@ changes:
 	@echo "The overview file is in $(BUILDDIR)/changes."
 
 linkcheck:
-	$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
+	$(SPHINXBUILD) -n -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
 	@echo
 	@echo "Link check complete; look for any errors in the above output " \
 	      "or in $(BUILDDIR)/linkcheck/output.txt."

diff --git a/docs/format/make.bat b/docs/format/make.bat
@@ -185,7 +185,7 @@ if "%1" == "changes" (
 )
 
 if "%1" == "linkcheck" (
-	%SPHINXBUILD% -b linkcheck %ALLSPHINXOPTS% %BUILDDIR%/linkcheck
+	%SPHINXBUILD% -n -b linkcheck %ALLSPHINXOPTS% %BUILDDIR%/linkcheck
 	if errorlevel 1 exit /b 1
 	echo.
 	echo.Link check complete; look for any errors in the above output ^

diff --git a/docs/format/source/format_description.rst b/docs/format/source/format_description.rst
@@ -19,7 +19,7 @@ The NWB format uses the following main primitives to hierarchically organize neu
 
 The NWB format is formally described via formal specification documents using the `NWB specification language <http://schema-language.readthedocs.io/en/latest/>`_ .
 HDF5 currently serves as the main format for storing data in the NWB format (see http://nwb-storage.readthedocs.io/en/latest/ for details).
-The `PyNWB <http://pynwb.readthedocs.io/en/latest/>`_ API is available to enable users to efficiently interact with NWB format files.
+The `PyNWB <http://pynwb.readthedocs.io/en/stable/>`_ API is available to enable users to efficiently interact with NWB format files.
 
 The NWB format uses a modular design in which all main semantic components of the format have
 a unique *neurodata_type* (similar to a Class in object-oriented design)(:numref:`sec_neurodata_type_intro`).
@@ -172,7 +172,7 @@ To ease development of extensions, the PyNWB_
 (and `HDMF <https://github.com/hdmf-dev/hdmf>`_ used by PyNWB) API provides dedicated
 data structures that support programmatic creation and use of extensions. An
 example for extending NWB using PyNWB_ is available at
-https://pynwb.readthedocs.io/en/stable/extensions.html and
+https://pynwb.readthedocs.io/en/stable/tutorials/general/extensions.html and
 additional details are also available as part of the PyNWB_ tutorials
 https://pynwb.readthedocs.io/en/stable/tutorials/index.html .
 

diff --git a/docs/format/source/format_release_notes.rst b/docs/format/source/format_release_notes.rst
@@ -176,7 +176,7 @@ Bug Fixes
 
 - Use "text" data type for electrode table columns "location" and "group_name". Previously, only ASCII was allowed.
 
-- Added to description to make electrode x,y,z consistent with CCF reference. http://help.brain-map.org/display/mousebrain/API#API-DownloadAtlas3-DReferenceModels
+- Added to description to make electrode x,y,z consistent with CCF reference. https://allensdk.readthedocs.io/en/latest/reference_space.html
 
 - Added "position" dataset with compound data type x,y,z in ElectrodeGroup.
 
@@ -378,7 +378,7 @@ Support row-based and column-based tables
       easy to add rows by appending to a single dataset, 3) make it easy to read individual rows
       of a table (but require reading the full table to extract the data of a single column).
       Row-based tables are used to simplify, e.g., the organization of electrode-metadata in NWB 2 (see above).
-      (See the `specification language release notes <http://schema-language.readthedocs.io/en/latest/specification_language_release_notes.html#release-notes>`_
+      (See the `specification language release notes <https://schema-language.readthedocs.io/en/latest/release_notes.html>`_
       for details about the addition of compound data types in the schema).
 
       * *Referencing rows in a row-based tables:* Subsets of rows can referenced directly via a region-reference to the
@@ -661,7 +661,7 @@ To address this challenge, NWB 2 added an optional top-level group ``units/`` (w
 ``/intervals/units``)  which is a :ref:`DynamicTable <sec-DynamicTable>`
 with ``id`` and ``description`` columns and optional additional user-defined table columns.
 See `PR597 on PyNWB <https://github.com/NeurodataWithoutBorders/pynwb/pull/597>`_ for detailed code changes. See
-the `PyNWB docs <https://pynwb.readthedocs.io/en/latest/tutorials/general/file.html#units>`__ for a
+the `PyNWB docs <https://pynwb.readthedocs.io/en/stable/tutorials/general/plot_read_basics.html#access-single-unit-data>`__ for a
 short tutorial on how to use unit metadata. See :ref:`NWBFile <sec-NWBFile>` *Groups: /units* for an overview of the
 unit schema.
 
@@ -792,7 +792,7 @@ Improved support for trial-based data
 **Format Changes:** Added optional group ``/intervals/trials/`` which is a :ref:`DynamicTable <sec-DynamicTable>`
 with ``id``, ``start_time``, and ``stop_time`` columns and optional additional user-defined table columns.
 See `PR536 on PyNWB <https://github.com/NeurodataWithoutBorders/pynwb/pull/536/files>`_ for detailed code changes. See
-the `PyNWB docs <https://pynwb.readthedocs.io/en/latest/tutorials/general/file.html?highlight=Trial#trials>`__ for a
+the `PyNWB docs <https://pynwb.readthedocs.io/en/stable/tutorials/general/plot_file.html#trials>`__ for a
 short tutorial on how to use trials. See :ref:`NWBFile <sec-NWBFile>` *Groups: /trials* for an overview of the trial
 schema. **Note:** Originally trials was added a top-level group trials which was then later moved to ``/intervals/trials``
 as part of the generalization of time interval storage as part of
@@ -1052,7 +1052,7 @@ Specification language changes
 **Change:** Numerous changes have been made to the specification language itself in NWB 2.0. Most changes to
 the specification language effect mainly how the format is specified, rather than the actual structure of the format.
 The changes that have implications on the format itself are described next. For an overview and discussion of the
-changes to the specification language see `specification language release notes <http://schema-language.readthedocs.io/en/latest/specification_language_release_notes.html#release-notes>`_.
+changes to the specification language see `specification language release notes <https://schema-language.readthedocs.io/en/latest/release_notes.html>`_.
 
 Specification of dataset dimensions
 """""""""""""""""""""""""""""""""""

diff --git a/docs/format/source/software_process.rst b/docs/format/source/software_process.rst
@@ -128,7 +128,7 @@ could point to two different versions of the schema.
 For the same reason, it is important that all public releases of the APIs, PyNWB and MatNWB, contain a publicly
 released version of nwb-schema. Starting with nwb-schema version 2.2.0, the dev branch and all public releases of PyNWB
 and MatNWB include only publicly released versions of nwb-schema. For more details, see the
-[PyNWB software process documentation](https://pynwb.readthedocs.io/en/latest/software_process.html).
+[PyNWB software process documentation](https://pynwb.readthedocs.io/en/stable/software_process.html).
 
 The [NWB Extensions Versioning Guidelines](https://nwb-extensions.github.io/versioning_guidelines) are used to guide
 versioning of the NWB core schema, as well as extensions to NWB.
diff --git a/requirements-doc.txt b/requirements-doc.txt
@@ -1,3 +1,5 @@
 hdmf-docutils
 pynwb
-matplotlib
+sphinx
+sphinx_rtd_theme
+matplotlib