CI: Docs validate (#497)

New `docs:validate` hatch script:
 - Check whether the docs build correctly
 - Validate external URLs in docs using linkchecker.

Runs on every commit in CI.

3 files changed, 38 insertions, 7 deletions

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 06da7e7..9e39598 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -82,9 +82,6 @@ jobs:
           hatch clean
         working-directory: ./gitlint-core
       
-      - name: Docs build (mkdocs)
-        run: hatch run docs:build
-
       # Run gitlint. Skip during PR runs, since PR commit messages are transient and usually full of gitlint violations.
       # PRs get squashed and get a proper commit message during merge.
       - name: gitlint --debug
@@ -100,6 +97,24 @@ jobs:
           flag-name: gitlint-${{ matrix.os }}-${{ matrix.python-version }}
           parallel: true
 
+  doc_checks:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3.3.0
+        with:
+          ref: ${{ github.event.pull_request.head.sha }} # Checkout pull request HEAD commit instead of merge commit
+
+      - name: Setup python
+        uses: actions/setup-python@v4.6.0
+        with:
+          python-version: 3.11
+
+      - name: Install Hatch
+        run: python -m pip install hatch==1.6.3
+
+      - name: Docs validation (mkdocs build & linkchecker)
+        run: hatch run docs:validate
+  
   upload_coveralls:
     needs: checks
     runs-on: ubuntu-latest
@@ -115,8 +130,9 @@ jobs:
     if: always()  # Ref: https://github.com/marketplace/actions/alls-green#why
 
     needs:
-      - upload_coveralls
       - checks
+      - doc_checks
+      - upload_coveralls
 
     runs-on: ubuntu-latest
 
@@ -130,6 +146,8 @@ jobs:
   auto-publish-dev:
     needs:
       - check
+      - doc_checks
+
     if: github.ref == 'refs/heads/main'
     uses: ./.github/workflows/publish-release.yml
     secrets: inherit # pass all secrets (required to access secrets in a called workflow)
diff --git a/mkdocs.yml b/mkdocs.yml
index f2074ab..cc81126 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -1,6 +1,6 @@
 site_name: Gitlint
 site_description: Linting for your git commit messages
-site_url: https://jorisroovers.github.io/gitlint/
+site_url: https://jorisroovers.github.io/gitlint/latest
 repo_url: https://github.com/jorisroovers/gitlint
 repo_name: jorisroovers/gitlint
 strict: true
diff --git a/pyproject.toml b/pyproject.toml
index 162d3ad..717438c 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -92,7 +92,7 @@ dependencies = [
     "radon==5.1.0",
     "pdbr==0.8.2; sys_platform != \"win32\"",
     "mypy==1.1.1",
-    "types-python-dateutil==2.8.19.12"
+    "types-python-dateutil==2.8.19.12",
 ]
 
 [tool.hatch.envs.test.scripts]
@@ -152,12 +152,25 @@ dependencies = [
     "mkdocs-redirects==1.2.0",
     # https://github.com/jimporter/mike/issues/130
     "mike @ https://github.com/jimporter/mike/archive/300593c338b18f61f604d18457c351e166318020.zip",
+    "linkchecker==10.2.1",
 ]
 
 [tool.hatch.envs.docs.scripts]
 build = "mkdocs build --clean --strict"
 serve = "mike serve"
 
+validate = [
+    "build", #
+    # Check all links in the docs
+    # Ignore 404.html and sitemap.xml since those contain absolute URLs to the site, 
+    # which are missing the /gitlint prefix that is automatically added when hosting on github pages.
+    # Also: don't bombard github.com with requests (will lead to 429 errors)
+    """
+    linkchecker --check-extern --ignore sitemap.xml --ignore 404.html \
+        --ignore-url https://github.com/jorisroovers/gitlint/ site
+    """,
+]
+
 # Tool config ##########################################################################################################
 
 [tool.black]
@@ -255,4 +268,4 @@ disable_error_code = ["import", "no-untyped-call"]
 # Ignore all errors in qa/shell.py (excluding this file isn't working because mypy include/exclude semantics
 # are unintuitive, so we ignore all errors instead)
 module = "qa.shell"
-ignore_errors  = true
+ignore_errors = true