Feature/901 provide switch to deactivate documentation

.github/workflows/fast-tests-extension.yml

@@ -18,7 +18,7 @@ jobs:
 
       - name: Set up Python & Poetry Environment
         id: set-up-python-and-poetry-environment
-        uses: exasol/python-toolbox/.github/actions/python-environment@v8
+        uses: exasol/python-toolbox/.github/actions/python-environment@v10
         with:
           python-version: "3.10"
           poetry-version: "2.3.0"

.github/workflows/slow-checks.yml

@@ -33,7 +33,7 @@ jobs:
 
       - name: Set up Python & Poetry Environment
         id: set-up-python-and-poetry-environment
-        uses: exasol/python-toolbox/.github/actions/python-environment@v8
+        uses: exasol/python-toolbox/.github/actions/python-environment@v10
         with:
           python-version: ${{ matrix.python_versions }}
           poetry-version: "2.3.0"

doc/changes/unreleased.md

@@ -1,3 +1,12 @@
 # Unreleased
 
 ## Summary
+
+This minor release adds an opt-out for documentation-enabled workflows and jobs. Projects can
+now declare that they do not serve documentation with the `has_documentation` switch in
+`BaseConfig`, and the workflow generator/checker will stop documentation relevant jobs
+and workflows for those projects. This should only be set to `False` for exceptional cases.
+
+## Feature
+
+* #901: Provided switch `has_documentation` in `BaseConfig` for projects without documentation

doc/user_guide/features/github_workflows/create_and_update.rst

@@ -85,6 +85,17 @@ used when you :ref:`install or update your workflows <update_workflows>`.
   generated, each removed job or modified step_id is checked to see if it exists.
   If it does not exist, an exception will be raised (:ref:`workflow_exceptions`).
 
+Projects Without Documentation
+------------------------------
+
+Most projects using the PTB should serve Sphinx-based documentation. For
+exceptional cases where a project does not serve documentation, set
+:py:attr:`exasol.toolbox.config.BaseConfig.has_documentation` to ``False`` in
+the project configuration.
+
+When this switch is disabled, the PTB no longer generates or expects documentation
+relevant parts in the GitHub workflows.
+
 .. _update_workflows:
 
 Add all Workflows to Your Project

exasol/toolbox/config.py

@@ -211,6 +211,17 @@ class BaseConfig(BaseModel):
         """,
     )
 
+    model_config = ConfigDict(frozen=True, arbitrary_types_allowed=True)
+
+    @computed_field  # type: ignore[misc]
+    @property
+    def has_documentation(self) -> bool:
+        """
+        Indicates that the project serves Sphinx-based documentation. With a few
+        exceptions, this should be the case for most projects.
+        """
+        return True
+
     @computed_field  # type: ignore[misc]
     @property
     def sonar_token_name(self) -> str:
@@ -221,8 +232,6 @@ def sonar_token_name(self) -> str:
         """
         return "SONAR_TOKEN"
 
-    model_config = ConfigDict(frozen=True, arbitrary_types_allowed=True)
-
     @computed_field  # type: ignore[misc]
     @property
     def documentation_path(self) -> Path:
@@ -327,6 +336,7 @@ def github_template_dict(self) -> dict[str, Any]:
         return {
             "custom_workflows": custom_workflow_extractor.build_custom_workflow_dict(),
             "dependency_manager_version": self.dependency_manager.version,
+            "has_documentation": self.has_documentation,
             "minimum_python_version": self.minimum_python_version,
             "os_version": self.os_version,
             "python_versions": self.python_versions,

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

@@ -40,6 +40,7 @@ jobs:
       contents: write
   (% endif %)
 
+  (% if has_documentation %)
   publish-docs:
     needs:
       - build-and-publish
@@ -49,3 +50,4 @@ jobs:
       contents: read
       pages: write
       id-token: write
+  (% endif %)

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

@@ -5,6 +5,7 @@ on:
   workflow_call:
 
 jobs:
+  (% if has_documentation %)
   build-documentation-and-check-links:
     name: Docs
     runs-on: "(( os_version ))"
@@ -31,6 +32,7 @@ jobs:
       - name: Check Links
         id: check-links
         run: poetry run -- nox -s links:check
+  (% endif %)
 
   check-changelog-was-updated:
     name: Check Changelog was Updated

exasol/toolbox/util/workflows/templates.py

@@ -1,5 +1,6 @@
 from collections.abc import Mapping
 from pathlib import Path
+from typing import Final
 
 import importlib_resources as resources
 
@@ -9,7 +10,8 @@
 )
 
 WORKFLOW_TEMPLATES_DIRECTORY = "exasol.toolbox.templates.github.workflows"
-NOT_MAINTAINED_WORKFLOW_NAMES: list[str] = ["slow-checks"]
+NOT_MAINTAINED_WORKFLOW_NAMES: Final[list[str]] = ["slow-checks"]
+DOCUMENTATION_ONLY_WORKFLOW_NAMES: Final[list[str]] = ["pr-merge"]
 
 
 def get_workflow_templates() -> Mapping[str, Path]:

exasol/toolbox/util/workflows/workflow_orchestrator.py

@@ -25,6 +25,7 @@
     WorkflowPatcher,
 )
 from exasol.toolbox.util.workflows.templates import (
+    DOCUMENTATION_ONLY_WORKFLOW_NAMES,
     WORKFLOW_TEMPLATE_OPTIONS,
     validate_workflow_name,
 )
@@ -110,7 +111,7 @@ def _load_workflow(
     def _skip_workflow(self, workflow_name: str, is_new_project: bool) -> bool:
         """
         Return ``True`` if the workflow should be skipped because it is not maintained
-        by the PTB, otherwise return ``False``.
+        by the PTB or not applicable to the current project, otherwise return ``False``.
         """
         try:
             validate_workflow_name(workflow_name)
@@ -121,6 +122,17 @@ def _skip_workflow(self, workflow_name: str, is_new_project: bool) -> bool:
                     workflow_name,
                 )
                 return True
+
+        if (
+            workflow_name in DOCUMENTATION_ONLY_WORKFLOW_NAMES
+            and not self.config.has_documentation
+        ):
+            logger.debug(
+                "Skipping documentation workflow for project without documentation: %s",
+                workflow_name,
+            )
+            return True
+
         return False
 
     def generate_workflows(self) -> None:

test/unit/config_test.py

@@ -44,6 +44,7 @@ def test_works_as_defined(tmp_path, test_project_config_factory):
             "create_major_version_tags": False,
             "dependency_manager": {"name": "poetry", "version": "2.3.0"},
             "documentation_path": root_path / "doc",
+            "has_documentation": True,
             "exasol_versions": ("8.29.13", "2025.1.8"),
             "excluded_python_paths": expand_paths(config, DEFAULT_EXCLUDED_PATHS),
             "github_workflow_directory": tmp_path / ".github" / "workflows",
@@ -57,6 +58,7 @@ def test_works_as_defined(tmp_path, test_project_config_factory):
                     "merge-gate": {"exists": True, "secrets": ("SONAR_TOKEN",)},
                 },
                 "dependency_manager_version": "2.3.0",
+                "has_documentation": True,
                 "minimum_python_version": "3.10",
                 "os_version": "ubuntu-24.04",
                 "python_versions": (