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)