Make CSS colors flexible

.github/workflows/antsibull-docs.yml

@@ -37,7 +37,7 @@ jobs:
         antsibull_docs_parser_ref:
           - main
         include:
-          - options: '--use-current --use-html-blobs --no-breadcrumbs community.crypto community.docker'
+          - options: '--use-current --use-html-blobs --no-breadcrumbs community.crypto community.docker --extra-conf antsibull_ext_color_scheme=none'
             python: '3.9'
           - options: '--use-current --output-format simplified-rst community.crypto community.docker'
             python: '3.11'

changelogs/fragments/254-theme-colors.yml

@@ -0,0 +1,2 @@
+minor_changes:
+  - "The colors used by the CSS provided by the Antsibull Sphinx extension can now be overridden (https://github.com/ansible-community/antsibull-docs/pull/254)."

docs/index.md

@@ -35,6 +35,15 @@ The `sphinx_antsibull_ext` [Sphinx extension](https://www.sphinx-doc.org/en/mast
 extensions = ['sphinx.ext.autodoc', 'sphinx.ext.intersphinx', 'notfound.extension', 'sphinx_antsibull_ext']
 ```
 
+It is possible to configure the color scheme used by the extension using the `antsibull_ext_color_scheme` configuration. Currently, two values are supported:
+
+1. `default`: the default colors.
+2. `none`: define no colors. You can use this if you want to override all colors by your own definition and thus have no need for the default colors to be included.
+
+The default color scheme can be found in [src/sphinx_antsibull_ext/css/colors-default.scss](https://github.com/ansible-community/antsibull-docs/blob/main/src/sphinx_antsibull_ext/css/colors-default.scss). See the [MDN page on using CSS custom properties](https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties) for information on how the color definitions work.
+
+Please note that the color scheme only works for HTML output. The colors for LaTeX / PDF output are hardcoded and currently cannot be modified.
+
 ## License
 
 Unless otherwise noted in the code, it is licensed under the terms of the GNU

src/sphinx_antsibull_ext/assets.py

@@ -12,6 +12,7 @@
 import os
 import pkgutil
 
+from sphinx.config import ENUM
 from sphinx.util.osutil import ensuredir
 
 BUILDER_FILES = {
@@ -53,6 +54,39 @@
     if _builder_name not in BUILDER_FILES and _alias in BUILDER_FILES:
         BUILDER_FILES[_builder_name] = BUILDER_FILES[_alias]
 
+_AVAILABLE_COLOR_SCHEMES = [
+    "none",
+    "default",
+]
+
+
+def get_color_scheme_content(color_scheme: str) -> bytes:
+    if color_scheme == "none":
+        return b""
+
+    filename = f"colors-{color_scheme}.css"
+    data = pkgutil.get_data("sphinx_antsibull_ext", filename)
+    if data is not None:
+        return data
+    raise RuntimeError(
+        f"Internal error: cannot find {filename} in sphinx_antsibull_ext package"
+    )
+
+
+def substitue_color_scheme(data: bytes, color_scheme: str) -> bytes:
+    return data.replace(
+        b"/* INSERT COLOR SCHEME HERE */", get_color_scheme_content(color_scheme)
+    )
+
+
+def get_color_scheme(app) -> str:
+    color_scheme = app.config.antsibull_ext_color_scheme
+    if color_scheme not in _AVAILABLE_COLOR_SCHEMES:
+        schemes = ", ".join(_AVAILABLE_COLOR_SCHEMES)
+        msg = f"Color scheme {color_scheme!r} is not available. Use one of {schemes}."
+        raise RuntimeError(f"Antsibull Sphinx extension: {msg}")
+    return color_scheme
+
 
 def _copy_asset_files(app):
     """
@@ -64,6 +98,9 @@ def _copy_asset_files(app):
             raise RuntimeError(
                 f"Internal error: cannot find {file} in sphinx_antsibull_ext package"
             )
+        if file == "antsibull-minimal.css":
+            data = substitue_color_scheme(data, color_scheme=get_color_scheme(app))
+
         path = os.path.join(app.outdir, directory) if directory else app.outdir
         ensuredir(path)
         destination = os.path.join(path, file)
@@ -100,6 +137,14 @@ def setup_assets(app):
     """
     Setup assets for a Sphinx app object.
     """
+    # Add CSS related options
+    app.add_config_value(
+        "antsibull_ext_color_scheme",
+        default="default",
+        rebuild="",
+        types=ENUM(*_AVAILABLE_COLOR_SCHEMES),
+    )
+
     # Copy assets
     app.connect("builder-inited", _copy_asset_files_inited)
     app.connect("build-finished", _copy_asset_files_finished)

src/sphinx_antsibull_ext/colors-default.css.license

@@ -0,0 +1,3 @@
+GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
+SPDX-FileCopyrightText: Ansible and contributors
+SPDX-License-Identifier: GPL-3.0-or-later