fix: use separate tooling env for settings-doc

fix: well that didn't work

fix: update tasks

fix: format settings doc files

Author: ryuwd

.env.example

@@ -97,3 +97,6 @@ docs/source/_build
 pixi.lock
 *.egg-info
 docs/templates/_builtin_markdown.jinja
+
+# docs site
+site

.gitignore

@@ -2,12 +2,10 @@
 
 *This page is auto-generated from the settings classes in `diracx.core.settings`.*
 
-
 ## AuthSettings
 
 Settings for the authentication service.
 
-
 ### `DIRACX_SERVICE_AUTH_DIRAC_CLIENT_ID`
 
 *Optional*, default value: `myDIRACClientID`
@@ -107,14 +105,10 @@ Set of security properties available in this DIRAC installation.
 These properties define various authorization capabilities and are used
 for access control decisions. Defaults to all available security properties.
 
-
-
-
 ## SandboxStoreSettings
 
 Settings for the sandbox store.
 
-
 ### `DIRACX_SANDBOX_STORE_BUCKET_NAME`
 
 **Required**
@@ -154,14 +148,10 @@ Logical name of the Storage Element for the sandbox store.
 This name is used within DIRAC to refer to this sandbox storage
 endpoint in job descriptions and file catalogs.
 
-
-
-
 ## OTELSettings
 
 Settings for the Open Telemetry Configuration.
 
-
 ### `DIRACX_OTEL_ENABLED`
 
 *Optional*, default value: `False`
@@ -172,7 +162,7 @@ Settings for the Open Telemetry Configuration.
 
 ### `DIRACX_OTEL_GRPC_ENDPOINT`
 
-*Optional*, default value: ``
+*Optional*, default value: \`\`
 
 ### `DIRACX_OTEL_GRPC_INSECURE`
 

docs/admin/reference/env-variables.md

@@ -30,10 +30,6 @@ diracx-logic = { path = "diracx-logic", editable = true, extras = ["testing"] }
 [feature.diracx-routers.pypi-dependencies]
 diracx-routers = { path = "diracx-routers", editable = true, extras = ["testing"] }
 
-# Settings documentation feature
-[feature.settings-doc.pypi-dependencies]
-settings-doc = "*"
-
 # DiracX features for providing tasks. This is needed to make it so that running
 # "pixi run pytest-diracx-core -vvv --pdb" passes the arguments as expected.
 # See: https://github.com/prefix-dev/pixi/issues/1519#issuecomment-2651078457
@@ -61,11 +57,6 @@ description = "Run the tests for diracx-logic"
 cmd = "cd diracx-routers/ && pytest"
 description = "Run the tests for diracx-routers"
 
-# Settings documentation task
-[feature.settings-doc.tasks.generate-settings-doc]
-cmd = "python scripts/generate_settings_docs.py"
-description = "Auto-discover and generate settings documentation with validation"
-
 # Gubbins features for providing dependencies
 [feature.gubbins.pypi-dependencies]
 gubbins = { path = "extensions/gubbins", editable = true, extras = ["testing"] }
@@ -149,6 +140,22 @@ shellcheck = "*"
 cmd = "find . -not -wholename './.pixi/*' -name '*.sh' -print -exec shellcheck --exclude=SC1090,SC1091 --external-source '{}' ';'"
 description = "Run shellcheck on all shell scripts"
 
+# Settings documentation feature
+[feature.settings-doc.dependencies]
+python = "*"
+[feature.settings-doc.pypi-dependencies]
+settings-doc = "*"
+mdformat = "*"
+mdformat-mkdocs = "*"
+mdformat-gfm = "*"
+mdformat-black = "*"
+diracx-core = { path = "diracx-core", editable = true }
+diracx-routers = { path = "diracx-routers", editable = true }
+# Settings documentation task
+[feature.settings-doc.tasks.generate-settings-doc]
+cmd = "python scripts/generate_settings_docs.py"
+description = "Auto-discover and generate settings documentation with validation"
+
 [environments]
 # DiracX environments
 default = {features = ["task-diracx", "diracx", "diracx-core", "diracx-api", "diracx-cli", "diracx-client", "diracx-db", "diracx-logic", "diracx-routers", "settings-doc"], solve-group = "diracx"}
@@ -177,6 +184,7 @@ gubbins-generate-client = {features = ["client-gen", "diracx-client", "gubbins-c
 mkdocs = {features = ["mkdocs"], no-default-feature = true}
 shellcheck = {features = ["shellcheck"], no-default-feature = true}
 pre-commit = {features = ["pre-commit"], no-default-feature = true}
+settings-doc = {features = ["settings-doc"], no-default-feature = true}
 
 # Meta-tasks for running many tests at once
 [tasks.pytest-diracx-all-one-by-one]

pixi.toml

@@ -17,6 +17,7 @@
 import pkgutil
 import re
 import shutil
+import subprocess
 import sys
 from pathlib import Path
 from typing import Any
@@ -212,7 +213,7 @@ def generate_all_templates(
     settings_classes: dict[str, dict],
     docs_dir: Path,
     repo_root: Path,
-) -> None:
+) -> list:
     """Generate documentation for all discovered templates."""
     # Collect all unique modules that contain settings
     modules = sorted(set(info["module"] for info in settings_classes.values()))
@@ -334,6 +335,23 @@ def compare_and_update_files(
     def normalize(text: str) -> str:
         return "\n".join(line for line in text.splitlines() if line.strip())
 
+    # First, run mdformat on all .bak files to ensure consistent formatting
+    backup_files = [backup for _, backup in generated_files]
+    if backup_files:
+        try:
+            subprocess.run(  # noqa: S603
+                ["mdformat", "--number"] + [str(f) for f in backup_files],
+                check=True,
+                capture_output=True,
+                text=True,
+            )
+        except subprocess.CalledProcessError as e:
+            print(f"⚠️  mdformat failed: {e.stderr}")
+            return False
+        except FileNotFoundError:
+            print("⚠️  mdformat not found in environment")
+            return False
+
     all_up_to_date = True
 
     for original_file, backup_file in generated_files:
@@ -401,10 +419,10 @@ def main():
         templates, settings_classes, docs_dir, repo_root
     )
 
-    print("\n📝 Generating .env file...")
-    dotenv_path = repo_root / ".env.example"
-    dotenv_backup = generate_dotenv_file(settings_classes, dotenv_path)
-    generated_files.append((dotenv_path, dotenv_backup))
+    # print("\n📝 Generating .env file...")
+    # dotenv_path = repo_root / ".env.example"
+    # dotenv_backup = generate_dotenv_file(settings_classes, dotenv_path)
+    # generated_files.append((dotenv_path, dotenv_backup))
 
     # Update files if they're different
     print("\n📝 Updating files...")