Add support for multi version documentation (#264)

Nicoretti · web-flow · commit f7912425554b · 2024-11-08T17:28:44.000+01:00
diff --git a/.github/workflows/gh-pages.yml b/.github/workflows/gh-pages.yml
@@ -16,7 +16,7 @@ jobs:
 
       - name: Build Documentation
         run: |
-          poetry run python -m nox -s build-docs
+          poetry run sphinx-multiversion docs/ .html-documentation 
 
       - name: Deploy
         uses: JamesIves/github-pages-deploy-action@v4.6.3
diff --git a/doc/_templates/version.html b/doc/_templates/version.html
diff --git a/doc/changes/unreleased.md b/doc/changes/unreleased.md
@@ -4,15 +4,19 @@
 
 * Dropped python 3.8 support
 
+## ✨ Added
+
+* Added support for multi version Documentation
+
 ## 🐞 Fixed
 
 * Fixed CD workflow template
 
 ## 📚 Documentation
 
-* Add Documentation on Metrics
+* Added Documentation on Metrics
 
 ## 🔩 Internal
 
-* Relock dependencies
+* Relocked dependencies
 
diff --git a/doc/conf.py b/doc/conf.py
@@ -38,6 +38,7 @@
     "sphinx_design",
     "sphinx_inline_tabs",
     "sphinx_copybutton",
+    "exasol.toolbox.sphinx.multiversion",
 ]
 
 intersphinx_mapping = {"python": ("https://docs.python.org/3", None)}
diff --git a/doc/user_guide/modules/sphinx/multiversion/conf.py b/doc/user_guide/modules/sphinx/multiversion/conf.py
@@ -1,4 +1,5 @@
 """Sphinx configuration file."""
+
 import time
 
 author = "Jan Holthuis"
diff --git a/exasol/toolbox/metrics.py b/exasol/toolbox/metrics.py
@@ -157,7 +157,14 @@ def char(value: str, default: str = "H") -> str:
             return value[0]
         return default
 
-    weight = {"LL": 1/18, "LM": 1/15, "LH": 1/12, "ML": 1/9, "MM": 1/6, "MH": 1/3}
+    weight = {
+        "LL": 1 / 18,
+        "LM": 1 / 15,
+        "LH": 1 / 12,
+        "ML": 1 / 9,
+        "MM": 1 / 6,
+        "MH": 1 / 3,
+    }
     exp = 0.0
     for infos in ratings:
         severity = infos["issue_severity"]
diff --git a/exasol/toolbox/nox/_lint.py b/exasol/toolbox/nox/_lint.py
@@ -11,14 +11,15 @@
 
 def _pylint(session: Session, files: Iterable[str]) -> None:
     session.run(
-            "poetry",
-            "run",
-            "python",
-            "-m",
-            "pylint",
-            "--output-format",
-            "colorized,json:.lint.json,text:.lint.txt",
-            *files)
+        "poetry",
+        "run",
+        "python",
+        "-m",
+        "pylint",
+        "--output-format",
+        "colorized,json:.lint.json,text:.lint.txt",
+        *files,
+    )
 
 
 def _type_check(session: Session, files: Iterable[str]) -> None:
diff --git a/exasol/toolbox/nox/_shared.py b/exasol/toolbox/nox/_shared.py
@@ -65,7 +65,7 @@ def _context(session: Session, **kwargs: Any) -> MutableMapping[str, Any]:
     parser = _context_parser()
     namespace, args = parser.parse_known_args(session.posargs)
     cli_context: MutableMapping[str, Any] = vars(namespace)
-    cli_context['fwd-args'] = args
+    cli_context["fwd-args"] = args
     default_context = {"db_version": "7.1.9", "coverage": False}
     # Note: ChainMap scans last to first
     return ChainMap(kwargs, cli_context, default_context)
diff --git a/exasol/toolbox/nox/_test.py b/exasol/toolbox/nox/_test.py
@@ -28,7 +28,7 @@ def _test_command(
         else []
     )
     pytest_command = ["pytest", "-v", f"{path}"]
-    return base_command + coverage_command + pytest_command + context['fwd-args']
+    return base_command + coverage_command + pytest_command + context["fwd-args"]
 
 
 def _unit_tests(
diff --git a/exasol/toolbox/sphinx/multiversion/__init__.py b/exasol/toolbox/sphinx/multiversion/__init__.py
@@ -10,18 +10,16 @@
 
 So huge thanks to the original author `Jan Holthuis <https://github.com/Holzhaus>`_ and all contributors.
 
-TODO's:
-* add standard default templates
-* add support for index page
-* add sorting support
-* add gh pages support
-* add command to deploy to gh-pages
-* add support for loading packed version template?
+
+NOTE:
+The original version and its defaults were minimally adjusted to work in Exasol's projects with the defaults and without adding an extra template. The [Shibuya](https://github.com/lepture/shibuya) theme is expected to be used for HTML, which already evaluates the versions field in the HTML context and generates an appropriate selector for the versions.
 """
 
 from exasol.toolbox.sphinx.multiversion.main import main
+from exasol.toolbox.sphinx.multiversion.sphinx import setup
+from exasol.toolbox.version import VERSION
 
-__version__ = "0.1.0"
+__version__ = VERSION
 
 __all__ = [
     "setup",
diff --git a/exasol/toolbox/sphinx/multiversion/main.py b/exasol/toolbox/sphinx/multiversion/main.py
@@ -566,7 +566,7 @@ def _main(args, argv):
                     export_to_destination(matches, export_dst)
 
         with resources.path(
-            "exasol.sphinx_extensions.multiversion.templates", "multiversion-index.html"
+            "exasol.toolbox.sphinx.multiversion.templates", "multiversion-index.html"
         ) as p:
             with open(p, encoding="utf-8") as f:
                 template = Template(f.read())
diff --git a/exasol/toolbox/sphinx/multiversion/sphinx.py b/exasol/toolbox/sphinx/multiversion/sphinx.py
@@ -9,11 +9,13 @@
 from sphinx.locale import _
 from sphinx.util import i18n as sphinx_i18n
 
+from exasol.toolbox.version import VERSION
+
 logger = logging.getLogger(__name__)
 
 DATE_FMT = "%Y-%m-%d %H:%M:%S %z"
-DEFAULT_TAG_WHITELIST = r"^.*$"
-DEFAULT_BRANCH_WHITELIST = r"^.*$"
+DEFAULT_TAG_WHITELIST = r"^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$"
+DEFAULT_BRANCH_WHITELIST = r"(master|main)"
 DEFAULT_REMOTE_WHITELIST = None
 DEFAULT_RELEASED_PATTERN = r"^tags/.*$"
 DEFAULT_OUTPUTDIR_FORMAT = r"{ref.name}"
@@ -40,6 +42,37 @@
 )
 
 
+class TagFormatError(Exception):
+    """
+    Exception raised for errors in the tag format.
+
+    The exception is raised when a tag is found to be incorrectly formatted.
+    """
+
+
+class ExasolVersionTag:
+
+    def __init__(self, version):
+        try:
+            v = version.name.strip()
+            parts = v.split(".")
+            major, minor, patch = map(int, parts)
+        except Exception as ex:
+            msg = f"Invalid tag format: '{version}', details: {ex}"
+            raise TagFormatError(msg) from ex
+
+        self._version = version
+        self._version_tripple = (major, minor, patch)
+
+    @property
+    def version(self):
+        return self._version
+
+    @property
+    def version_triple(self):
+        return self._version_tripple
+
+
 class VersionInfo:
     def __init__(self, app, context, metadata, current_version_name):
         self.app = app
@@ -94,8 +127,10 @@ def in_development(self):
         ]
 
     def __iter__(self):
-        yield from self.tags
         yield from self.branches
+        yield from sorted(
+            self.tags, key=lambda t: ExasolVersionTag(t).version_triple, reverse=True
+        )
 
     def __getitem__(self, name):
         v = self.metadata.get(name)
@@ -183,7 +218,8 @@ def html_page_context(app, pagename, templatename, context, doctree):
     context["vhasdoc"] = versioninfo.vhasdoc
     context["vpathto"] = versioninfo.vpathto
 
-    context["current_version"] = versioninfo[app.config.smv_current_version]
+    current = versioninfo[app.config.smv_current_version]
+    context["current_version"] = current.name
     context["latest_version"] = versioninfo[app.config.smv_latest_version]
     context["html_theme"] = app.config.html_theme
 
@@ -247,7 +283,7 @@ def setup(app):
     app.connect("config-inited", config_inited)
 
     return {
-        "version": "0.2",
+        "version": VERSION,
         "parallel_read_safe": True,
         "parallel_write_safe": True,
     }
diff --git a/exasol/toolbox/templates/github/workflows/gh-pages.yml b/exasol/toolbox/templates/github/workflows/gh-pages.yml
@@ -16,7 +16,7 @@ jobs:
 
       - name: Build Documentation
         run: |
-          poetry run python -m nox -s build-docs
+          poetry run sphinx-multiversion docs/ .html-documentation 
 
       - name: Deploy
         uses: JamesIves/github-pages-deploy-action@v4.6.0
diff --git a/exasol/toolbox/tools/security.py b/exasol/toolbox/tools/security.py
@@ -1,4 +1,5 @@
 """This module contains security related CLI tools and code"""
+
 import json
 import re
 import subprocess
diff --git a/noxconfig.py b/noxconfig.py
@@ -1,4 +1,5 @@
 """Configuration for nox based task runner"""
+
 from __future__ import annotations
 
 from dataclasses import dataclass
@@ -35,8 +36,15 @@ class Config:
     root: Path = Path(__file__).parent
     doc: Path = Path(__file__).parent / "doc"
     version_file: Path = Path(__file__).parent / "exasol" / "toolbox" / "version.py"
-    path_filters: Iterable[str] = ("dist", ".eggs", "venv", "metrics-schema", "project-template", "idioms")
+    path_filters: Iterable[str] = (
+        "dist",
+        ".eggs",
+        "venv",
+        "metrics-schema",
+        "project-template",
+        "idioms",
+    )
     plugins = [UpdateTemplates]
-    
+
 
 PROJECT_CONFIG = Config()
diff --git a/noxfile.py b/noxfile.py
@@ -1,4 +1,5 @@
 """defines nox tasks/targets for this project"""
+
 import nox
 
 # imports all nox task provided by the toolbox
@@ -7,6 +8,7 @@
 # default actions to be run if nothing is explicitly specified with the -s option
 nox.options.sessions = ["fix"]
 
+
 # entry point for debugging
 def main() -> None:
     """
diff --git a/poetry.lock b/poetry.lock
diff --git a/pyproject.toml b/pyproject.toml
@@ -55,21 +55,16 @@ sphinx-copybutton = "^0.5.0"
 sphinx-inline-tabs = "^2023.4.21"
 sphinx-design = ">=0.5.0,<1"
 typer = {extras = ["all"], version = ">=0.7.0"}
-
-
 bandit = {extras = ["toml"], version = "^1.7.9"}
+jinja2 = "^3.1.4"
+
 [tool.poetry.group.dev.dependencies]
 autoimport = "^1.4.0"
 
 [build-system]
 requires = ["poetry-core"]
 build-backend = "poetry.core.masonry.api"
 
-
-[tool.poetry.plugins."console_scripts"]
-"sphinx-multiversion" = "exasol.toolbox.sphinx.multiversion.main:main"
-"version-check" = "exasol.toolbox.pre_commit_hooks.package_version:main"
-
 # Tooling
 [tool.coverage.run]
 relative_files = true
@@ -108,5 +103,10 @@ module = [
 ]
 ignore_errors = true
 
+[tool.poetry.plugins."console_scripts"]
+"version-check" = "exasol.toolbox.pre_commit_hooks.package_version:main"
+
+
 [tool.poetry.scripts]
 tbx = 'exasol.toolbox.tools.tbx:CLI'
+sphinx-multiversion = 'exasol.toolbox.sphinx.multiversion:main'

Original file line number	Diff line number	Diff line change
`@@ -38,6 +38,7 @@`
`38`	`38`	`"sphinx_design",`
`39`	`39`	`"sphinx_inline_tabs",`
`40`	`40`	`"sphinx_copybutton",`
	`41`	`+ "exasol.toolbox.sphinx.multiversion",`
`41`	`42`	`]`
`42`	`43`
`43`	`44`	`intersphinx_mapping = {"python": ("https://docs.python.org/3", None)}`
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,5 @@`
`1`	`1`	`"""Sphinx configuration file."""`
	`2`	`+`
`2`	`3`	`import time`
`3`	`4`
`4`	`5`	`author = "Jan Holthuis"`
Original file line number	Diff line number	Diff line change
`@@ -28,7 +28,7 @@ def _test_command(`
`28`	`28`	`else []`
`29`	`29`	`)`
`30`	`30`	`pytest_command = ["pytest", "-v", f"{path}"]`
`31`		`- return base_command + coverage_command + pytest_command + context['fwd-args']`
	`31`	`+ return base_command + coverage_command + pytest_command + context["fwd-args"]`
`32`	`32`
`33`	`33`
`34`	`34`	`def _unit_tests(`