From c3ec4c61420cfd0bfe8a10febffe18c76459e7c8 Mon Sep 17 00:00:00 2001 From: atheeq <168955553+xtheeq@users.noreply.github.com> Date: Tue, 12 May 2026 19:48:45 +0530 Subject: [PATCH] =?UTF-8?q?refactor(nix):=20replace=20sync=20nix=20options?= =?UTF-8?q?=20with=20direct=20md=20generation=20to=20=E2=80=A6=20(#1)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * 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 | 80 +++++++++++++++++++ .../workflows/generate-nix-options-docs.yml | 58 ++++++++++++++ .github/workflows/sync-nix-options.yml | 59 -------------- .gitignore | 1 - docs/meta.json | 1 + nix/hm-modules.nix | 1 - 6 files changed, 139 insertions(+), 61 deletions(-) create mode 100755 .github/scripts/generate-nix-options-docs.py create mode 100644 .github/workflows/generate-nix-options-docs.yml delete mode 100644 .github/workflows/sync-nix-options.yml diff --git a/.github/scripts/generate-nix-options-docs.py b/.github/scripts/generate-nix-options-docs.py new file mode 100755 index 00000000..23cd3b90 --- /dev/null +++ b/.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('<', '<').replace('>', '>').replace('\n', '
') + return f"{safe_html}" + + return f"`{val_text}`" + +def main(): + if len(sys.argv) != 4: + sys.exit("Usage: format_docs.py ") + + 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('|', '|') + 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() diff --git a/.github/workflows/generate-nix-options-docs.yml b/.github/workflows/generate-nix-options-docs.yml new file mode 100644 index 00000000..e5fd0df2 --- /dev/null +++ b/.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 }} diff --git a/.github/workflows/sync-nix-options.yml b/.github/workflows/sync-nix-options.yml deleted file mode 100644 index 3e05f0e1..00000000 --- a/.github/workflows/sync-nix-options.yml +++ /dev/null @@ -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 diff --git a/.gitignore b/.gitignore index 274cc4ee..7681f948 100644 --- a/.gitignore +++ b/.gitignore @@ -1,7 +1,6 @@ /.cache /.vscode /result -/result-* config.h mango mango.o diff --git a/docs/meta.json b/docs/meta.json index 74818a9d..8c10c621 100644 --- a/docs/meta.json +++ b/docs/meta.json @@ -11,6 +11,7 @@ "window-management", "bindings", "---Reference---", + "nix-options", "ipc", "faq" ] diff --git a/nix/hm-modules.nix b/nix/hm-modules.nix index f9a341a3..f00d9c68 100644 --- a/nix/hm-modules.nix +++ b/nix/hm-modules.nix @@ -22,7 +22,6 @@ in enable = mkOption { type = types.bool; default = false; - description = "Whether to enable mangowm, a Wayland compositor based on dwl."; }; package = lib.mkOption { type = lib.types.package;