refactor(nix): replace sync nix options with direct md generation to … (#1)

* refactor(nix): replace sync nix options with direct md generation to docs

* fix(docs): add trailing comman in meta

* fix(ci): sort nix options and fix default value check

.github/scripts/generate-nix-options-docs.py

@@ -0,0 +1,80 @@
+#!/usr/bin/env python3
+"""
+Converts NixOS options JSON into clean, table-formatted Markdown.
+"""
+
+import json
+import sys
+import re
+
+def clean_description(desc: str) -> str:
+    """Removes Nix tags, fixes dangling periods, and formats blockquotes."""
+    if not desc:
+        return "*No description provided.*"
+
+    desc = re.sub(r'\{[a-zA-Z]+\}', '', desc).replace('\n.', '.')
+
+    lines = desc.splitlines()
+    cleaned = []
+    in_note = False
+    
+    for line in lines:
+        if line.startswith("::: {.note"):
+            in_note = True
+            cleaned.append("> **Note:**\n>")
+        elif line.startswith(":::"):
+            in_note = False
+        else:
+            cleaned.append(f"> {line}" if in_note else line)
+
+    return "\n".join(cleaned)
+
+def format_default_value(default_data) -> str:
+    """Safely formats the default value, handling HTML escaping for tables."""
+    if default_data is None:
+        return "*None*"
+
+    val_text = default_data.get("text", "") if isinstance(default_data, dict) and default_data.get("_type") == "literalExpression" else str(default_data)
+    val_text = val_text.replace('|', '|')
+
+    if '\n' in val_text:
+        safe_html = val_text.replace('<', '&lt;').replace('>', '&gt;').replace('\n', '<br>')
+        return f"<code>{safe_html}</code>"
+    
+    return f"`{val_text}`"
+
+def main():
+    if len(sys.argv) != 4:
+        sys.exit("Usage: format_docs.py <input.json> <output.md> <title>")
+
+    input_json, output_md, title = sys.argv[1:4]
+
+    with open(input_json, 'r', encoding='utf-8') as f:
+        data = json.load(f)
+
+    with open(output_md, 'a', encoding='utf-8') as out:
+        out.write(f"## {title}\n\n")
+
+        for key, opt in sorted(data.items()):
+            if key.startswith("_module"):
+                continue
+
+            desc = clean_description(opt.get("description", ""))
+            opt_type = str(opt.get("type", "unknown")).replace('|', '&#124;')
+            default_val = format_default_value(opt.get("default"))
+            
+            markdown_block = (
+                f"### `{key}`\n\n"
+                f"{desc}\n\n"
+                f"| Attribute | Value |\n"
+                f"| :--- | :--- |\n"
+                f"| **Type** | `{opt_type}` |\n"
+                f"| **Default** | {default_val} |\n\n"
+                f"---\n\n"
+            )
+            out.write(markdown_block)
+
+    print(f"Appended {title} to {output_md} successfully.")
+
+if __name__ == "__main__":
+    main()

.github/workflows/generate-nix-options-docs.yml

@@ -0,0 +1,58 @@
+name: Generate Nix Options Docs
+
+on:
+  push:
+    paths:
+      - 'nix/**-modules.nix'
+      - 'nix/generate-options.nix'
+      - 'flake.nix'
+  pull_request:
+    paths:
+      - 'nix/**-modules.nix'
+
+jobs:
+  update-docs:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          ref: ${{ github.head_ref }}
+
+      - name: Install Nix
+        uses: cachix/install-nix-action@v30
+        with:
+          extra_nix_config: |
+            experimental-features = nix-command flakes
+
+      - name: Build Options JSON
+        run: |
+          nix build .#nixos-options-json --out-link result-nixos
+          nix build .#hm-options-json --out-link result-hm
+
+      - name: Format to Markdown
+        run: |
+          OUTPUT_FILE="docs/nix-options.md"
+          
+          cat << 'EOF' > $OUTPUT_FILE
+          ---
+          title: Nix Module Options
+          description: NixOS and Home Manager configuration options for mangowm.
+          ---
+          
+          > **Note:** This document is automatically generated from the Nix module source code.
+          
+          EOF
+          
+          python3 ./.github/scripts/generate-nix-options-docs.py result-nixos/share/doc/nixos/options.json $OUTPUT_FILE "NixOS Module Options"
+          python3 ./.github/scripts/generate-nix-options-docs.py result-hm/share/doc/nixos/options.json $OUTPUT_FILE "Home Manager Options"
+
+      - name: Auto-commit changes
+        uses: stefanzweifel/git-auto-commit-action@v5
+        with:
+          commit_message: "docs: auto-generate Nix module options"
+          file_pattern: 'docs/*-options.md'
+          branch: ${{ github.head_ref }}

.github/workflows/sync-nix-options.yml

@@ -1,59 +0,0 @@
-name: Sync Nix module options
-
-on:
-  push:
-    branches: [main]
-    paths:
-      - nix/hm-modules.nix
-      - nix/nixos-modules.nix
-      - nix/generate-options.nix
-      - flake.nix
-      - flake.lock
-
-concurrency:
-  group: sync-nix-options
-  cancel-in-progress: true
-
-jobs:
-  sync-nix-options:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-        with:
-          fetch-depth: 1
-
-      - uses: cachix/install-nix-action@v30
-        with:
-          extra_nix_config: |
-            experimental-features = nix-command flakes
-
-      - name: Build options JSONs
-        run: |
-          HM_OUT=$(nix build .#hm-options-json --no-link --print-out-paths)
-          NIXOS_OUT=$(nix build .#nixos-options-json --no-link --print-out-paths)
-          cp "$HM_OUT/share/doc/nixos/options.json" /tmp/hm-options.json
-          cp "$NIXOS_OUT/share/doc/nixos/options.json" /tmp/nixos-options.json
-
-      - name: Checkout website
-        uses: actions/checkout@v4
-        with:
-          repository: mangowm/mangowm.github.io
-          path: website
-          token: ${{ secrets.WEBSITE_SYNC_TOKEN }}
-          fetch-depth: 1
-
-      - name: Copy JSONs to website
-        run: |
-          cp /tmp/hm-options.json website/apps/web/src/hm-options.json
-          cp /tmp/nixos-options.json website/apps/web/src/nixos-options.json
-
-      - name: Commit and push
-        working-directory: website
-        run: |
-          git config user.name "github-actions[bot]"
-          git config user.email "github-actions[bot]@users.noreply.github.com"
-          git add apps/web/src/hm-options.json apps/web/src/nixos-options.json
-          git diff --staged --quiet || git commit \
-            -m "nix: update module options JSON" \
-            -m "${{ github.server_url }}/${{ github.repository }}/commit/${{ github.sha }}"
-          git push