doc

Author: Jannis-Mittenzwei

.github/workflows/checks.yml

@@ -39,22 +39,11 @@ jobs:
         run: |
           poetry run -- nox -s docs:build
 
-  Documentation-Links:
-    name: Doc Links Check
-    runs-on: ubuntu-24.04
-    permissions:
-      contents: read
-    steps:
-      - name: SCM Checkout
-        uses: actions/checkout@v4
-
-      - name: Setup Python & Poetry Environment
-        uses: ./.github/actions/python-environment
-
       - name: Link Check
         run: |
           poetry run -- nox -s docs:links:check
 
+
   Changelog:
     name: Changelog Update Check
     runs-on: ubuntu-24.04

doc/changes/unreleased.md

@@ -2,5 +2,30 @@
 
 ## Summary
 
+### Links in the Documentation 
+This version of the PTB adds nox tasks to check links present in our documentation:
+
+    docs:link - List all the links within the documentation
+    docs:links:check - Checks whether all links in the documentation are accessible
+
+`docs:links:check` is run in the CI `checks.yml`. If this step fails in the CI,
+please check the output & manually resolve the issues. There might be some cases
+where you need to update your doc/conf.py with specific values for the allowed
+options for the Linkcheck Builder.
+
+We recommend the following values be added:
+
+    linkcheck_rate_limit_timeout = 40
+    linkcheck_timeout = 10
+    linkcheck_delay = 20
+    linkcheck_retries = 2
+    linkcheck_anchors = False
+    linkcheck_ignore: list[str] = []
+    linkcheck_allowed_redirects = {
+        # All HTTP redirections from the source URI to
+        # the canonical URI will be treated as "working".
+        r"https://github\.com/.*": r"https://github\.com/login*"
+    }
+
 ## ✨ Features
 * #409: Doc link & checks

exasol/toolbox/nox/_documentation.py

@@ -101,8 +101,8 @@ def _docs_list_links(doc_config: Path):
                 doc_config,
                 tmpdir,
             ],
-            capture_output= True,
-            text= True
+            capture_output=True,
+            text=True,
         )
         if sp.returncode >= 2:
             return sp.returncode, sp.stderr
@@ -116,17 +116,9 @@ def _docs_list_links(doc_config: Path):
                     file_links.append(line)
         file_links.sort(key=lambda file: file["filename"])
         return 0, "\n".join(
-                f"filename: {fl['filename']}:{fl['lineno']} -> uri: {fl['uri']}" for fl in file_links
-            )
-
-
-@nox.session(name="docs:links", python=False)
-def docs_list_links(session: Session) -> None:
-    """List all the links within the documentation."""
-    r_code, text = _docs_list_links(PROJECT_CONFIG.doc)
-    print(text)
-    if r_code != 0:
-        session.error()
+            f"filename: {fl['filename']}:{fl['lineno']} -> uri: {fl['uri']}"
+            for fl in file_links
+        )
 
 
 def _docs_links_check(doc_config: Path, args):
@@ -146,7 +138,18 @@ def _docs_links_check(doc_config: Path, args):
             dst = Path(args.output) / "link-check-output.json"
             shutil.copyfile(result_json, dst)
             print(f"file generated at path: {result_json.resolve()}")
-        return sp.returncode, None if sp.returncode >= 2 else (tmpdir / "output.txt").read_text()
+        return sp.returncode, (
+            None if sp.returncode >= 2 else (tmpdir / "output.txt").read_text()
+        )
+
+
+@nox.session(name="docs:links", python=False)
+def docs_list_links(session: Session) -> None:
+    """List all the links within the documentation."""
+    r_code, text = _docs_list_links(PROJECT_CONFIG.doc)
+    print(text)
+    if r_code != 0:
+        session.error()
 
 
 @nox.session(name="docs:links:check", python=False)
@@ -158,15 +161,15 @@ def docs_links_check(session: Session) -> None:
         formatter_class=argparse.ArgumentDefaultsHelpFormatter,
     )
     parser.add_argument(
-        "-o", "--output", type=Path, help="path to output file", default=None
+        "-o", "--output", type=Path, help="path to copy the output json", default=None
     )
     args = parser.parse_args(session.posargs)
     r_code, problems = _docs_links_check(PROJECT_CONFIG.doc, args)
     if r_code >= 2:
         session.error(2)
     if r_code == 1 or problems != "":
-        escape_rot = "\033[31m"
-        print(escape_rot + "errors:")
+        escape_red = "\033[31m"
+        print(escape_red + "errors:")
         print(problems)
         session.error(1)
 

exasol/toolbox/templates/github/workflows/checks.yml

@@ -38,6 +38,10 @@ jobs:
         run: |
           poetry run -- nox -s docs:build
 
+      - name: Link Check
+        run: |
+          poetry run -- nox -s docs:links:check
+
   build-matrix:
     name: Generate Build Matrix
     uses: ./.github/workflows/matrix-python.yml

project-template/{{cookiecutter.repo_name}}/doc/conf.py

@@ -76,5 +76,16 @@
     "github_url": "https://github.com/exasol/{{cookiecutter.repo_name}}",
     "accent_color": "grass",
 }
+
 # -- Configure link checking behavior  ----------------------------------------
-linkcheck_rate_limit_timeout = 15
+linkcheck_rate_limit_timeout = 40
+linkcheck_timeout = 10
+linkcheck_delay = 20
+linkcheck_retries = 2
+linkcheck_anchors = False
+linkcheck_ignore: list[str] = []
+linkcheck_allowed_redirects = {
+    # All HTTP redirections from the source URI to
+    # the canonical URI will be treated as "working".
+    r"https://github\.com/.*": r"https://github\.com/login*"
+}

test/unit/documentation_test.py

@@ -1,11 +1,16 @@
+import shutil
+from unittest.mock import (
+    MagicMock,
+    patch,
+)
+
 import pytest
-from unittest.mock import patch, MagicMock
+
 import exasol.toolbox.nox._documentation
 from exasol.toolbox.nox._documentation import (
+    _docs_links_check,
     _docs_list_links,
-    _docs_links_check
 )
-import shutil
 from noxconfig import Config
 
 
@@ -28,9 +33,10 @@ def index():
 
    file"""
 
+
 @pytest.fixture()
 def expected1():
-        return """filename: file.rst:2 -> uri: https://examle.invalid"""
+    return """filename: file.rst:2 -> uri: https://examle.invalid"""
 
 
 def config(index, file, tmp_path):
@@ -55,27 +61,36 @@ def test_docs_links(index, file1, expected1, tmp_path):
 @pytest.mark.parametrize(
     "file2, expected2",
     [
-        (
-            "https://httpbin.org/status/200",
-            (0, "")
-        ),
+        ("https://httpbin.org/status/200", (0, "")),
         (
             "https://httpbin.org/status/301",
-            (0, "file.rst:1: [redirected with Found] https://httpbin.org/status/301 to https://httpbin.org/get\n")
+            (
+                0,
+                "file.rst:1: [redirected with Found] https://httpbin.org/status/301 to https://httpbin.org/get\n",
+            ),
         ),
         (
             "https://httpbin.org/status/302",
-            (0, "file.rst:1: [redirected with Found] https://httpbin.org/status/302 to https://httpbin.org/get\n")
+            (
+                0,
+                "file.rst:1: [redirected with Found] https://httpbin.org/status/302 to https://httpbin.org/get\n",
+            ),
         ),
         (
             "https://httpbin.org/status/303",
-            (0, "file.rst:1: [redirected with Found] https://httpbin.org/status/303 to https://httpbin.org/get\n")
+            (
+                0,
+                "file.rst:1: [redirected with Found] https://httpbin.org/status/303 to https://httpbin.org/get\n",
+            ),
         ),
         (
             "https://httpbin.org/status/404",
-            (1, "file.rst:1: [broken] https://httpbin.org/status/404: 404 Client Error: NOT FOUND for url: https://httpbin.org/status/404\n")
-        )
-    ]
+            (
+                1,
+                "file.rst:1: [broken] https://httpbin.org/status/404: 404 Client Error: NOT FOUND for url: https://httpbin.org/status/404\n",
+            ),
+        ),
+    ],
 )
 def test_docs_links_check(index, file2, expected2, tmp_path):
     config(index, file2, tmp_path)