Better checking for external links (#619)

.github/scripts/link-check.sh → .github/scripts/make-docs.sh

@@ -3,4 +3,4 @@ source $(dirname ${BASH_SOURCE[0]})/common.sh
 ci_conda_activate
 cd docs
 source install-deps
-make linkcheck
+make docs

.github/workflows/release.yaml

@@ -13,8 +13,8 @@ jobs:
       - uses: actions/checkout@v3
       - name: Install conda
         run: .github/scripts/install-conda.sh
-      - name: Documentation Link Check
-        run: .github/scripts/link-check.sh
+      - name: Make Docs
+        run: .github/scripts/make-docs.sh
       - name: Format Check
         run: .github/scripts/format-check.sh
       - name: Make Package

.github/workflows/test.yaml

@@ -17,8 +17,8 @@ jobs:
       - uses: actions/checkout@v3
       - name: Install conda
         run: .github/scripts/install-conda.sh
-      - name: Documentation Link Check
-        run: .github/scripts/link-check.sh
+      - name: Make Docs
+        run: .github/scripts/make-docs.sh
       - name: Format Check
         run: .github/scripts/format-check.sh
       - name: Test

docs/Makefile

@@ -1,10 +1,9 @@
 BUILDDIR     = build
-LINKCHECKDIR = $(BUILDDIR)/linkcheck
 SOURCEDIR    = .
 SPHINXBUILD  = sphinx-build
 SPHINXOPTS   = -a -n -W --keep-going
 
-.PHONY: help clean docs examples linkcheck
+.PHONY: help clean docs examples
 
 help:
 	$(SPHINXBUILD) -M help $(SOURCEDIR) $(BUILDDIR) $(SPHINXOPTS)
@@ -13,15 +12,12 @@ clean:
 	$(RM) -rv $(BUILDDIR)
 
 docs:
-	$(MAKE) linkcheck
 	$(MAKE) html
+	linkchecker --check-extern --no-warnings build/html/index.html
 
 examples:
 	COLUMNS=80 $(MAKE) -C sections
 
-linkcheck:
-	$(SPHINXBUILD) -b linkcheck $(SPHINXOPTS) -c $(CURDIR) $(CURDIR) build/linkcheck
-
 %:
 	mkdir -pv $(BUILDDIR)
 	$(SPHINXBUILD) -M $@ $(SOURCEDIR) $(BUILDDIR) $(SPHINXOPTS) -w $(BUILDDIR)/warnings.log

docs/conf.py

@@ -21,7 +21,6 @@
 html_static_path = ["static"]
 html_theme = "sphinx_rtd_theme"
 intersphinx_mapping = {"python": ("https://docs.python.org/3", None)}
-linkcheck_ignore = [r"https://github.com/.*#.*"]
 nitpick_ignore_regex = [("py:class", r"^uwtools\..*"), ("py:class", "f90nml.Namelist")]
 numfig = True
 numfig_format = {"figure": "Figure %s"}

docs/deps

@@ -0,0 +1,18 @@
+#!/usr/bin/env python
+
+from pathlib import Path
+import re
+import yaml
+
+path = Path(__file__).parent / "environment.yml"
+with open(path, "r", encoding="utf-8") as f:
+    deps = yaml.safe_load(f)["dependencies"]
+specs = []
+for dep in deps:
+    m = re.match(r"([^ ]+) *(.*)", dep)
+    assert m
+    pkg, ver = m.groups()
+    if re.match(r"^\d", ver):
+        ver = f"={ver}"
+    specs.append(f"'{pkg}{ver}'")
+print(" ".join(sorted(specs)))

docs/environment.yml

@@ -2,7 +2,8 @@ name: readthedocs
 channels:
   - conda-forge
 dependencies:
-  - python=3.12
-  - sphinx_rtd_theme=2.0.*
-  - sphinxcontrib-bibtex=2.6.*
+  - linkchecker 10.4.*
+  - python >=3.9,<3.13 # keep in sync with meta.yaml run req
+  - sphinx_rtd_theme 3.0.*
+  - sphinxcontrib-bibtex 2.6.*
   - tree

docs/index.rst

@@ -77,7 +77,6 @@ File/Directory Provisioning
 | **CLI**: ``uw fs -h``
 | **API**: ``import uwtools.api.fs``
 
-
 This tool helps users define the source and destination of files to be copied or linked, or directories to be created, in the same UW YAML language used by UW drivers.
 
 | :any:`CLI documentation with examples<cli_fs_mode>`
@@ -86,7 +85,7 @@ There is a video demonstration of the use of the ``uw fs`` tool (formerly ``uw f
 
 .. raw:: html
 
-   <iframe width="560" height="315" src="https://www.youtube.com/embed/b2HXOlt-Ulw?si=rLWatBFu4mvNR65S" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe>
+   <iframe src="https://www.youtube.com/embed/b2HXOlt-Ulw" allowfullscreen frameborder="0" height="315" width="560"></iframe>
 
 Rocoto Configurability
 ^^^^^^^^^^^^^^^^^^^^^^

docs/install-deps

@@ -1 +1 @@
-conda install -q -y $(python -c "import yaml; f=open('$(dirname ${BASH_SOURCE[0]})/environment.yml'); print(' '.join(yaml.safe_load(f)['dependencies']))")
+conda install -q -y $($(dirname ${BASH_SOURCE[0]})/deps)

docs/sections/user_guide/cli/Makefile

@@ -5,4 +5,4 @@ SUBDIRS = $(shell find . -maxdepth 1 -mindepth 1 -type d | sort)
 all: $(SUBDIRS)
 
 $(SUBDIRS):
-	$(MAKE) -C $@ -j
+	@$(MAKE) -C $@ -j

docs/sections/user_guide/cli/Makefile.outputs

@@ -6,4 +6,4 @@ OUTPUTS  = $(COMMANDS:cmd=out)
 all: $(OUTPUTS)
 
 $(OUTPUTS):
-	bash $(basename $@).cmd >$@ 2>&1 | true
+	@bash $(basename $@).cmd >$@ 2>&1 | true

docs/sections/user_guide/cli/drivers/Makefile

@@ -5,4 +5,4 @@ SUBDIRS = $(filter-out ./shared,$(shell find . -maxdepth 1 -mindepth 1 -type d |
 all: $(SUBDIRS)
 
 $(SUBDIRS):
-	$(MAKE) -C $@ -j
+	@$(MAKE) -C $@ -j