add tests for doc links

Author: Jannis-Mittenzwei

doc/conf.py

@@ -80,7 +80,7 @@
 }
 # -- Configure link checking behavior  ----------------------------------------
 linkcheck_rate_limit_timeout = 40
-linkcheck_timeout = 5
+linkcheck_timeout = 10
 linkcheck_delay = 20
 linkcheck_retries = 2
 linkcheck_anchors = False

exasol/toolbox/nox/_documentation.py

@@ -2,26 +2,14 @@
 
 import argparse
 import json
-import os
-import re
 import shutil
 import subprocess
 import sys
 import tempfile
 import webbrowser
-from collections.abc import (
-    Container,
-    Iterable,
-)
-from itertools import repeat
 from pathlib import Path
-from typing import (
-    Optional,
-    Tuple,
-)
 
 import nox
-import requests  # type: ignore
 from nox import Session
 
 from exasol.toolbox.nox._shared import DOCS_OUTPUT_DIR
@@ -100,26 +88,24 @@ def clean_docs(_session: Session) -> None:
         shutil.rmtree(docs_folder)
 
 
-@nox.session(name="docs:links", python=False)
-def docs_list_links(session: Session) -> None:
-    """List all the links within the documentation."""
+def _docs_list_links(doc_config: Path):
     with tempfile.TemporaryDirectory() as path:
         tmpdir = Path(path)
-        sp = subprocess.run(
+        sp = subprocess.run(  # nosec
             [
                 "sphinx-build",
                 "-b",
                 "linkcheck",
                 "-D",
                 "linkcheck_ignore=.*",
-                PROJECT_CONFIG.root / "doc",
+                doc_config,
                 tmpdir,
             ],
+            capture_output= True,
+            text= True
         )
-        print(sp.returncode)
         if sp.returncode >= 2:
-            print(sp.stderr)
-            session.error(2)
+            return sp.returncode, sp.stderr
         output = tmpdir / "output.json"
         links = output.read_text().split("\n")
         file_links = []
@@ -129,51 +115,60 @@ def docs_list_links(session: Session) -> None:
                 if not line["uri"].startswith("#"):
                     file_links.append(line)
         file_links.sort(key=lambda file: file["filename"])
-        print(
-            "\n".join(
-                f"filename: {fl['filename']} -> uri: {fl['uri']}" for fl in file_links
+        return 0, "\n".join(
+                f"filename: {fl['filename']}:{fl['lineno']} -> uri: {fl['uri']}" for fl in file_links
             )
-        )
 
 
-@nox.session(name="docs:links:check", python=False)
-def docs_links_check(session: Session) -> None:
-    """Checks whether all links in the documentation are accessible."""
-    parser = argparse.ArgumentParser(
-        prog="nox -s release:prepare",
-        usage="nox -s release:prepare -- [-h] [-o |--output]",
-        formatter_class=argparse.ArgumentDefaultsHelpFormatter,
-    )
-    parser.add_argument(
-        "-o", "--output", type=Path, help="path to output file", default=None
-    )
-    args = parser.parse_args(session.posargs)
+@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()
+
+
+def _docs_links_check(doc_config: Path, args):
     with tempfile.TemporaryDirectory() as path:
         tmpdir = Path(path)
         sp = subprocess.run(
             [
                 "sphinx-build",
                 "-b",
                 "linkcheck",
-                PROJECT_CONFIG.root / "doc",
+                doc_config,
                 tmpdir,
             ],
         )
-        print(sp.returncode)
-        if sp.returncode >= 2:
-            print(sp.stderr)
-            session.error(2)
-        if args.output:
+        if args.output and sp.returncode <= 1:
             result_json = tmpdir / "output.json"
             dst = Path(args.output) / "link-check-output.json"
             shutil.copyfile(result_json, dst)
             print(f"file generated at path: {result_json.resolve()}")
-        result_txt = tmpdir / "output.txt"
-        if sp.returncode == 1 or result_txt.read_text() != "":
-            escape_rot = "\033[31m"
-            print(escape_rot + "errors:")
-            print(result_txt.read_text())
-            session.error(1)
+        return sp.returncode, None if sp.returncode >= 2 else (tmpdir / "output.txt").read_text()
+
+
+@nox.session(name="docs:links:check", python=False)
+def docs_links_check(session: Session) -> None:
+    """Checks whether all links in the documentation are accessible."""
+    parser = argparse.ArgumentParser(
+        prog="nox -s docs:links:check",
+        usage="nox -s docs:links:check -- [-h] [-o |--output]",
+        formatter_class=argparse.ArgumentDefaultsHelpFormatter,
+    )
+    parser.add_argument(
+        "-o", "--output", type=Path, help="path to output file", 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:")
+        print(problems)
+        session.error(1)
 
 
 @nox.session(name="changelog:updated", python=False)

test/unit/documentation_test.py

@@ -0,0 +1,88 @@
+import pytest
+from unittest.mock import patch, MagicMock
+import exasol.toolbox.nox._documentation
+from exasol.toolbox.nox._documentation import (
+    _docs_list_links,
+    _docs_links_check
+)
+import shutil
+from noxconfig import Config
+
+
+@pytest.fixture()
+def file1():
+    return """
+https://examle.invalid
+:ref:`Test`"""
+
+
+@pytest.fixture()
+def index():
+    return """.. _Test:
+Test
+____
+
+.. toctree::
+   :maxdepth: 1
+   :hidden:
+
+   file"""
+
+@pytest.fixture()
+def expected1():
+        return """filename: file.rst:2 -> uri: https://examle.invalid"""
+
+
+def config(index, file, tmp_path):
+    test_doc = tmp_path / "doc"
+    test_doc.mkdir()
+    (test_doc / "_static").mkdir()
+    shutil.copyfile(Config.doc / "conf.py", test_doc / "conf.py")
+    rst_index = test_doc / "index.rst"
+    rst_file1 = test_doc / "file.rst"
+    rst_index.touch()
+    rst_file1.touch()
+    rst_index.write_text(index)
+    rst_file1.write_text(file)
+
+
+def test_docs_links(index, file1, expected1, tmp_path):
+    config(index, file1, tmp_path)
+    r_code, text = _docs_list_links(tmp_path / "doc")
+    assert (text == expected1) and not r_code
+
+
+@pytest.mark.parametrize(
+    "file2, expected2",
+    [
+        (
+            "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")
+        ),
+        (
+            "https://httpbin.org/status/302",
+            (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")
+        ),
+        (
+            "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")
+        )
+    ]
+)
+def test_docs_links_check(index, file2, expected2, tmp_path):
+    config(index, file2, tmp_path)
+    args = MagicMock
+    args.output = None
+    actual = _docs_links_check(tmp_path / "doc", args)
+    print("______________________")
+    print(actual)
+    print("______________________")
+    assert actual == expected2