add doc:links and docs:links:check

.github/workflows/checks.yml

@@ -39,6 +39,22 @@ 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

@@ -24,6 +24,7 @@ At this time, PTB currently does not support setting up SonarQube for a **privat
 
 ## ✨ Features
 * #451: Added nox task to execute pysonar & added Sonar to the CI
+* #409: Doc link & checks
 
 ## ⚒️ Refactorings
 * #451: Reduced scope of nox tasks `lint:code` (pylint) and `lint:security` (bandit) to analyze only the package code

doc/conf.py

@@ -78,3 +78,15 @@
     "github_url": "https://github.com/exasol/python-toolbox",
     "accent_color": "grass",
 }
+# -- Configure link checking behavior  ----------------------------------------
+linkcheck_rate_limit_timeout = 40
+linkcheck_timeout = 5
+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*"
+}

doc/developer_guide/modules/sphinx/sphinx.rst

@@ -4,7 +4,7 @@ sphinx
 sphinx-multiversion
 +++++++++++++++++++
 
-The `sphinx-multiversion` extension is a modified copy of `Holzhaus/sphinx-multiversion <https://github.com/Holzhaus/sphinx-multiversion>`_. This copy was taken from version :code:`0.24.0`.
+The `sphinx-multiversion` extension is a modified copy of `Holzhaus/sphinx-multiversion <https://github.com/sphinx-contrib/multiversion>`_. This copy was taken from version :code:`0.24.0`.
 
 It has been adjusted with minor code changes and modified defaults to work seamlessly with Exasol integration projects, which often require a specific project structure and layout. Additionally, it is designed to be used with an HTML theme that supports displaying and selecting multiple versions if the `versions` variable is set in the HTML context of sphinx. As of this writing, the theme used in conjunction with this modified version of `sphinx-multiversion` is `SHIBUYA <https://github.com/lepture/shibuya>`_, version :code:`2024.10.15`.
 

doc/github_actions/security_issues.rst

@@ -112,4 +112,4 @@ Ideas
 .. todo::
 
     Consider adapting common CVE report format as input, for additional details
-    `see here <https://github.com/CVEProject/cve-schema/blob/master/schema/v5.0/CVE_JSON_5.0_schema.json>`_.
+    `see here <https://github.com/CVEProject/cve-schema/blob/main/schema/CVE_Record_Format.json>`_.

doc/styleguide/guides/idioms/idioms.rst

@@ -37,5 +37,5 @@ where we picked it up from, rather than the "original" source.
 
 
 .. _Raymond Hettinger: https://github.com/rhettinger
-.. _Transform Code into Beautiful, Idiomatic Python: https://www.youtube.com/watch?v=OSGv2VnC0go>
+.. _Transform Code into Beautiful, Idiomatic Python: https://www.youtube.com/watch?v=OSGv2VnC0go
 .. _Transform Python Slides: https://speakerdeck.com/pyconslides/transforming-code-into-beautiful-idiomatic-python-by-raymond-hettinger-1

doc/styleguide/guides/style.rst

@@ -54,10 +54,10 @@ _____
 .. _Google Styleguide: https://google.github.io/styleguide/pyguide.html
 .. _PEP 8: https://peps.python.org/pep-0008/
 .. _Python Idioms: https://gist.github.com/0x4D31/f0b633548d8e0cfb66ee3bea6a0deff9
-.. _Python Like You Mean It: http://www.pythonlikeyoumeanit.com/module_2.html>
+.. _Python Like You Mean It: http://www.pythonlikeyoumeanit.com/module_2.html
 .. _Python Programming Idioms: https://en.wikibooks.org/wiki/Python_Programming/Idioms
 
-.. _Transform Code into Beautiful, Idiomatic Python: https://www.youtube.com/watch?v=OSGv2VnC0go>
+.. _Transform Code into Beautiful, Idiomatic Python: https://www.youtube.com/watch?v=OSGv2VnC0go
 .. _Transform Python Slides: https://speakerdeck.com/pyconslides/transforming-code-into-beautiful-idiomatic-python-by-raymond-hettinger-1
 .. _Stop Writing Classes: https://www.youtube.com/watch?v=o9pEzgHorH0
 .. _Refactoring Python: https://www.youtube.com/watch?v=D_6ybDcU5gc

doc/user_guide/features.rst

@@ -7,13 +7,13 @@ Uniform Project Layout
 PTB expects a default project layout following "convention over configuration" when possible and reasonable.
 See the cookie-cutter project template for details, which is part of the python-toolbox workspace and can be found in directory `project-template`.
 You can also generate a project from the template to explore the default structure.
-For more details on this, please check out section `"getting started" <getting_started.html>`_ section.
+For more details on this, please check out section :ref:`Getting Started` section.
 
 Nox
 ---
 
 The most central tool when interacting with the toolbox is :code:`nox`, which is the task runner used across all of Exasol's Python-based projects.
-The toolbox itself provides various standard tasks and a plugin mechanism to extend these tasks if needed. For more information regarding nox, please visit the `nox homepage <http://nox.thea.codes/en/stable/>`_.
+The toolbox itself provides various standard tasks and a plugin mechanism to extend these tasks if needed. For more information regarding nox, please visit the `nox homepage <https://nox.thea.codes/en/stable/>`_.
 
 Central files in regards to nox and the toolbox are:
 

doc/user_guide/getting_started.rst

@@ -1,3 +1,5 @@
+.. _Getting Started:
+
 Getting Started
 ===============
 

exasol/toolbox/nox/_documentation.py

@@ -1,11 +1,27 @@
 from __future__ import annotations
 
+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
@@ -17,8 +33,6 @@
 
 def _build_docs(session: nox.Session, config: Config) -> None:
     session.run(
-        "poetry",
-        "run",
         "sphinx-build",
         "-W",
         "-b",
@@ -30,8 +44,6 @@ def _build_docs(session: nox.Session, config: Config) -> None:
 
 def _build_multiversion_docs(session: nox.Session, config: Config) -> None:
     session.run(
-        "poetry",
-        "run",
         "sphinx-multiversion",
         f"{config.doc}",
         DOCS_OUTPUT_DIR,
@@ -88,6 +100,82 @@ 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."""
+    with tempfile.TemporaryDirectory() as path:
+        tmpdir = Path(path)
+        sp = subprocess.run(
+            [
+                "sphinx-build",
+                "-b",
+                "linkcheck",
+                "-D",
+                "linkcheck_ignore=.*",
+                PROJECT_CONFIG.root / "doc",
+                tmpdir,
+            ],
+        )
+        print(sp.returncode)
+        if sp.returncode >= 2:
+            print(sp.stderr)
+            session.error(2)
+        output = tmpdir / "output.json"
+        links = output.read_text().split("\n")
+        file_links = []
+        for link in links:
+            if link != "":
+                line = json.loads(link)
+                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
+            )
+        )
+
+
+@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)
+    with tempfile.TemporaryDirectory() as path:
+        tmpdir = Path(path)
+        sp = subprocess.run(
+            [
+                "sphinx-build",
+                "-b",
+                "linkcheck",
+                PROJECT_CONFIG.root / "doc",
+                tmpdir,
+            ],
+        )
+        print(sp.returncode)
+        if sp.returncode >= 2:
+            print(sp.stderr)
+            session.error(2)
+        if args.output:
+            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)
+
+
 @nox.session(name="changelog:updated", python=False)
 def updated(_session: Session) -> None:
     """Checks if the change log has been updated"""