Add sphinx-lint and run it in CI

Author: snejus

.github/sphinx-problem-matcher.json

@@ -1,13 +1,30 @@
 {
   "problemMatcher": [
     {
-      "owner": "sphinx",
+      "owner": "sphinx-build",
       "pattern": [
         {
-          "regexp": "^([^:]+):(\\d+): (WARNING: )?(.+)$",
+          "regexp": "^([^:]+):\\s(.+)$",
+          "file": 1,
+          "message": 2
+        },
+        {
+          "regexp": "^([^:]+):(\\d+):\\s(.+)$",
+          "file": 1,
+          "line": 2,
+          "message": 3
+        }
+      ]
+    },
+    {
+      "owner": "sphinx-lint",
+      "pattern": [
+        {
+          "regexp": "^([^:]+):(\\d+):\\s+(.*)\\s\\(([a-z-]+)\\)$",
           "file": 1,
           "line": 2,
-          "message": 4
+          "message": 3,
+          "code": 4
         }
       ]
     }

.github/workflows/lint.yml

@@ -130,7 +130,7 @@ jobs:
         run: echo "::add-matcher::.github/sphinx-problem-matcher.json"
 
       - name: Build docs
-        run: |-
-          poe docs |& tee /tmp/output
-          # fail the job if there are issues
-          grep -q " WARNING:" /tmp/output && exit 1 || exit 0
+        run: poe docs -e SPHINXOPTS=--fail-on-warning
+
+      - name: Lint docs
+        run: poetry run sphinx-lint --enable all $(git ls-files docs)

poetry.lock

@@ -79,6 +79,7 @@ soco = { version = "*", optional = true }
 
 pydata-sphinx-theme = { version = "*", optional = true }
 sphinx = { version = "*", optional = true }
+sphinx-lint = { version = ">=1.0.0", optional = true }
 
 [tool.poetry.group.test.dependencies]
 beautifulsoup4 = "*"
@@ -127,7 +128,7 @@ beatport = ["requests-oauthlib"]
 bpd = ["PyGObject"] # gobject-introspection, gstreamer1.0-plugins-base, python3-gst-1.0
 chroma = ["pyacoustid"] # chromaprint or fpcalc
 # convert # ffmpeg
-docs = ["pydata-sphinx-theme", "sphinx"]
+docs = ["pydata-sphinx-theme", "sphinx", "sphinx-lint"]
 discogs = ["python3-discogs-client"]
 embedart = ["Pillow"] # ImageMagick
 embyupdate = ["requests"]
@@ -265,7 +266,7 @@ select = [
     "W", # pycodestyle
 ]
 ignore = [
-  "TC006"  # no need to quote 'cast's since we use 'from __future__ import annotations'
+    "TC006", # no need to quote 'cast's since we use 'from __future__ import annotations'
 ]
 
 [tool.ruff.lint.per-file-ignores]