From 35f6287765a53ac5826cdd172c6f28a11a21df52 Mon Sep 17 00:00:00 2001
From: Nicola Coretti <nicola.coretti@exasol.com>
Date: Tue, 10 Dec 2024 11:53:43 +0100
Subject: [PATCH] Add support for multiversion documentation build

---
 .github/workflows/gh-pages.yaml |  6 ++---
 .gitignore                      |  1 +
 doc/changes/unreleased.md       |  3 +++
 doc/conf.py                     |  1 +
 noxconfig.py                    | 26 ++++++++++++++++++
 noxfile.py                      | 48 ++++++++++-----------------------
 6 files changed, 48 insertions(+), 37 deletions(-)
 create mode 100644 noxconfig.py

diff --git a/.github/workflows/gh-pages.yaml b/.github/workflows/gh-pages.yaml
index 74ae5ebb..3dc7f5aa 100644
--- a/.github/workflows/gh-pages.yaml
+++ b/.github/workflows/gh-pages.yaml
@@ -21,14 +21,14 @@ jobs:
 
       - name: Build Documentation
         run: |
-          poetry run python -m nox -s build-docs
-          touch doc/build/.nojekyll
+          poetry run python -m nox -s docs:multiversion
+          touch .html-documentation/.nojekyll
 
       - name: Deploy
         uses: JamesIves/github-pages-deploy-action@v4.5.0
         with:
           branch: gh-pages
-          folder: ./doc/build
+          folder: .html-documentation
           git-config-name: Github Action
           git-config-email: opensource@exasol.com
 
diff --git a/.gitignore b/.gitignore
index 266eb950..71c57235 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,3 +1,4 @@
+.html-documentation
 odbcconfig/odbcinst.ini
 
 _build/
diff --git a/doc/changes/unreleased.md b/doc/changes/unreleased.md
index 6977a5c8..5d81eb3a 100644
--- a/doc/changes/unreleased.md
+++ b/doc/changes/unreleased.md
@@ -12,4 +12,7 @@
 - Remove testing against Exasol 7.0
 - Relocked dependencies
 
+## 📚 Documentation
+
+* Added support for multiversion documentation
 
diff --git a/doc/conf.py b/doc/conf.py
index bfebfb92..897e636f 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -36,6 +36,7 @@
     "sphinx_copybutton",
     "myst_parser",
     "sphinx_design",
+    "exasol.toolbox.sphinx.multiversion",
 ]
 
 intersphinx_mapping = {"python": ("https://docs.python.org/3", None)}
diff --git a/noxconfig.py b/noxconfig.py
new file mode 100644
index 00000000..87bee5c4
--- /dev/null
+++ b/noxconfig.py
@@ -0,0 +1,26 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import (
+    Iterable,
+)
+
+
+@dataclass(frozen=True)
+class Config:
+    root: Path = Path(__file__).parent
+    doc: Path = Path(__file__).parent / "doc"
+    version_file: Path = (
+        Path(__file__).parent / "sqlalchemy_exasol" / "version.py"
+    )
+    path_filters: Iterable[str] = (
+        "dist",
+        ".eggs",
+        "venv",
+    )
+
+    plugins = []
+
+
+PROJECT_CONFIG = Config()
diff --git a/noxfile.py b/noxfile.py
index 067bb68e..1d29bc9a 100644
--- a/noxfile.py
+++ b/noxfile.py
@@ -8,12 +8,14 @@
 from shutil import rmtree
 from tempfile import TemporaryDirectory
 
+# fmt: off
 PROJECT_ROOT = Path(__file__).parent
 # scripts path also contains administrative code/modules which are used by some nox targets
 SCRIPTS = PROJECT_ROOT / "scripts"
 DOC = PROJECT_ROOT / "doc"
 DOC_BUILD = DOC / "build"
 sys.path.append(f"{SCRIPTS}")
+# fmt: on
 
 from typing import Iterator
 
@@ -288,40 +290,6 @@ def parser() -> ArgumentParser:
     session.notify(find_session_runner(session, "db-stop"))
 
 
-@nox.session(python=False, name="clean-docs")
-def clean(session: Session) -> None:
-    """Remove all documentation artifacts"""
-    if DOC_BUILD.exists():
-        rmtree(DOC_BUILD.resolve())
-        session.log(f"Removed {DOC_BUILD}")
-
-
-@nox.session(python=False, name="build-docs")
-def build(session: Session) -> None:
-    """Build the documentation"""
-    session.run(
-        "poetry",
-        "run",
-        "sphinx-build",
-        "-b",
-        "html",
-        "-W",
-        f"{DOC}",
-        f"{DOC_BUILD}",
-        external=True,
-    )
-
-
-@nox.session(python=False, name="open-docs")
-def open_docs(session: Session) -> None:
-    """Open the documentation in the browser"""
-    index_page = DOC_BUILD / "index.html"
-    if not index_page.exists():
-        session.error(
-            f"File {index_page} does not exist." "Please run `nox -s build-docs` first"
-        )
-
-    webbrowser.open_new_tab(index_page.resolve().as_uri())
 
 
 @nox.session(python=False)
@@ -482,3 +450,15 @@ def list_links(session: Session) -> None:
     """List all links within the documentation"""
     for path, url in _urls(_documentation(PROJECT_ROOT)):
         session.log(f"Url: {url}, File: {path}")
+
+
+
+# fmt: off
+from exasol.toolbox.nox._documentation import (
+    build_docs,
+    build_multiversion,
+    clean_docs,
+    open_docs,
+    
+)
+# fmt: on