Fix #171: Document ENV config TOML file (#174)

* Fix #171: Document ENV config TOML file

* Generate the RST from TOML file through a Python script (`toml_parser.py`).
  It can be executed as a standalone script or integrated into Sphinx.
* Enhance `conf.py` to read the TOML config(s) and create the generated
  file. The generate file is included in `reference/env-toml/index.rst`.
* The generated file has a different extension than .rst (actually `.rst.inc`).
  This was necessary otherwise you get a warning from Sphinx about duplicate labels.
* Enrich the TOML file with comments similar to "docstrings": it contains
  the syntax "KEYNAME(TYPE): DESCRIPTION"
  This is a kind of "self-documenting" approach.
* Currently, the standard tomllib library doesn't preserve comments.
  To not rely on a different library, we need to read it line by line. :(
* There is a small optimization in the conf.py file: the .rst.inc file is
  only generated when the TOML file has a newer date.
* Use "github-action" group for CI test
* Use "uv lock --no-upgrade" to upgrade uv.lock file
* Rework regex
* Add UTF-8 encoding when writing RST
* Use UTF-8 encoding when reading TOML
* Fix comment
* Fix regexes for doc comments

---------
    
    Co-authored-by: Sushant Gaurav <[email protected]>

Author: tomschr

.github/workflows/ci.yml

@@ -29,8 +29,8 @@ env:
   UV_FROZEN: "1"
   # Needed for coverage/multiprocessing reliability
   PYTHONSTARTMETHOD: spawn
-  # The group to use for installing/testing dependencies
-  PYPROJECT_GROUP: tests
+  # The group to use for installing/testing dependencies, see pyproject.toml
+  PYPROJECT_GROUP: github-action
 
 jobs:
   test-ubuntu:

docs/source/conf.py

@@ -7,9 +7,19 @@
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
 
 from datetime import datetime
+from pathlib import Path
+import sys
+
+from sphinx.application import Sphinx
+from sphinx.errors import ExtensionError
+from sphinx.util import logging
 
 from docbuild.__about__ import __version__
 
+# Add the directory containing toml_parser.py to sys.path
+# If it's in the same directory as conf.py:
+sys.path.insert(0, str(Path(__file__).parent))
+
 project = "docbuild"
 current_year = datetime.now().year
 copyright = f"{current_year}, Tom Schraitle | Sushant Gaurav"  # noqa: A001
@@ -219,3 +229,63 @@
     # Just ignore useless example URLs
     r"https://github\.com/org/repo",
 ]
+
+
+# Configuration for TOML documentation generation
+# Format: (input_toml, output, {additional_config})
+# Paths are relative to the conf.py directory
+toml_doc_config = [
+    # 1
+    (
+        "../../etc/docbuild/env.example.toml",
+        "reference/env-toml/env-toml-ref.rst.inc",
+        {},  # Use default prefix, no need to add that.
+    ),
+]
+
+logger = logging.getLogger(__name__)
+
+
+def run_toml_generator(app: Sphinx) -> None:
+    """Run the TOML documentation generator before the build process starts."""
+    from toml_parser import generate_toml_reference
+
+    conf_dir = Path(app.confdir)
+    for input_rel, output_rel, config_data in toml_doc_config:
+        toml_input = (conf_dir / input_rel).resolve()
+        rst_output = (conf_dir / output_rel).resolve()
+
+        # Check if the input file exists before proceeding
+        if not toml_input.exists():
+            msg = (
+                "TOML documentation generation failed: "
+                f"Input file not found at {toml_input}"
+            )
+            logger.error(msg)
+            raise ExtensionError(msg)
+
+        # Optimization: Only generate if input is newer than output
+        if rst_output.exists():
+            input_mtime = toml_input.stat().st_mtime
+            output_mtime = rst_output.stat().st_mtime
+
+            if input_mtime <= output_mtime:
+                logger.info(
+                    "Skipping TOML reference generation: %s is up to date.",
+                    rst_output.name,
+                )
+                continue
+
+        # Ensure the directory exists
+        rst_output.parent.mkdir(parents=True, exist_ok=True)
+
+        logger.info(
+            "Generating TOML reference: %s -> %s", toml_input.name, rst_output.name
+        )
+        generate_toml_reference(toml_input, rst_output, **config_data)
+
+
+def setup(app: Sphinx) -> None:
+    """Sphinx setup function to connect the TOML generator to the build process."""
+    # This hook ensures the file exists before Sphinx tries to 'include' it
+    app.connect("builder-inited", run_toml_generator)