diff --git a/.github/scripts/generate-nix-options-docs.py b/.github/scripts/generate-nix-options-docs.py index 6f5d35bd..268edb5b 100755 --- a/.github/scripts/generate-nix-options-docs.py +++ b/.github/scripts/generate-nix-options-docs.py @@ -1,22 +1,9 @@ #!/usr/bin/env python3 -""" -Converts NixOS options JSON into clean Markdown documentation. -""" - -import json -import sys +# Post-processes nixos-render-docs commonmark output into a single docs page. +# Input: two pre-rendered .md files (NixOS and HM), produced by nixos-render-docs. +# Steps: strip internal _module.args section, promote ## headings to ###. import re - -SECTIONS = [ - { - "title": "NixOS", - "subtitle": "**System-level options via `programs.mango`.**", - }, - { - "title": "Home Manager", - "subtitle": "**Configure mangowm declaratively via `wayland.windowManager.mango`.**", - }, -] +import sys HEADER = ( "---\n" @@ -26,87 +13,36 @@ HEADER = ( "> **Note:** This document is automatically generated from the Nix module source code.\n\n" ) -def clean_description(desc: str) -> str: - """Strips Nix inline markup tags, fixes dangling periods, and formats blockquotes.""" - if not desc: - return "*No description provided.*" +SECTIONS = [ + ("NixOS", "**System-level options via `programs.mango`.**"), + ("Home Manager", "**Configure mangowm declaratively via `wayland.windowManager.mango`.**"), +] - # Strip Nix inline markup: {tag}`content` → `content`; bare tags → "" - desc = re.sub(r'\{(?:var|option|manpage|file|env|command|program)\}(`[^`]+`)', r'\1', desc) - desc = re.sub(r'\{(?:var|option|manpage|file|env|command|program)\}', '', desc) - # Remove period left on its own line after tag removal - desc = re.sub(r'\n\s*\.(\s|$)', r'.\1', desc) - lines = desc.splitlines() - cleaned = [] - in_block = False +def process(md): + # Remove internal _module.args option injected by the module system + md = re.sub(r'## _module\\\.args.*?(?=\n## |\Z)', '', md, flags=re.DOTALL) + # Promote option headings (##) to subheadings (###) under the section (##) + md = re.sub(r'^## ', '### ', md, flags=re.MULTILINE) + return md.strip() - for line in lines: - m = re.match(r':::\s*\{\.(\w+)\}', line) - if m: - block_type = m.group(1).capitalize() - in_block = True - cleaned.append(f"> **{block_type}:**\n>") - elif line.startswith(":::"): - in_block = False - else: - cleaned.append(f"> {line}" if in_block else line) - - return "\n".join(cleaned) - -def format_value(val_data) -> str: - """Formats a value as inline code or a nix code block.""" - if val_data is None: - return None - - if isinstance(val_data, dict) and val_data.get("_type") == "literalMD": - return val_data.get("text", "").strip() - elif isinstance(val_data, dict) and val_data.get("_type") == "literalExpression": - text = val_data.get("text", "").strip() - elif isinstance(val_data, bool): - text = "true" if val_data else "false" - elif val_data == {} or val_data == []: - text = "{ }" if val_data == {} else "[ ]" - else: - text = str(val_data).strip() - - if '\n' in text: - return f"\n```nix\n{text}\n```" - return f"`{text}`" - -def write_section(out, data, title, subtitle): - out.write(f"## {title}\n\n{subtitle}\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")) - default_val = format_value(opt.get("default")) - example_val = format_value(opt.get("example")) - - block = f"### `{key}`\n\n{desc}\n\n**Type:** `{opt_type}`\n\n" - if default_val is not None: - block += f"**Default:** {default_val}\n\n" - if example_val is not None: - block += f"**Example:** {example_val}\n\n" - block += "---\n\n" - out.write(block) def main(): if len(sys.argv) != 4: - sys.exit("Usage: generate-nix-options-docs.py ") + sys.exit("Usage: generate-nix-options-docs.py ") - nixos_json, hm_json, output_md = sys.argv[1:4] - inputs = [nixos_json, hm_json] + nixos_md, hm_md, output_md = sys.argv[1:4] with open(output_md, 'w', encoding='utf-8') as out: out.write(HEADER) - for path, section in zip(inputs, SECTIONS): + for path, (title, subtitle) in zip([nixos_md, hm_md], SECTIONS): with open(path, 'r', encoding='utf-8') as f: - data = json.load(f) - write_section(out, data, section["title"], section["subtitle"]) - print(f"Written {section['title']} section.") + md = f.read() + out.write(f"## {title}\n\n{subtitle}\n\n") + out.write(process(md)) + out.write('\n\n') + print(f"Written {title} section.") + if __name__ == "__main__": main() diff --git a/.github/workflows/generate-nix-options-docs.yml b/.github/workflows/generate-nix-options-docs.yml index 465146be..7249ef46 100644 --- a/.github/workflows/generate-nix-options-docs.yml +++ b/.github/workflows/generate-nix-options-docs.yml @@ -34,11 +34,25 @@ jobs: nix build .#nixos-options-json --out-link result-nixos nix build .#hm-options-json --out-link result-hm + - name: Render to CommonMark + run: | + echo '{}' > /tmp/manpage-urls.json + nix run nixpkgs#nixos-render-docs -- options commonmark \ + --manpage-urls /tmp/manpage-urls.json \ + --revision nightly \ + result-nixos/share/doc/nixos/options.json \ + /tmp/nixos-raw.md + nix run nixpkgs#nixos-render-docs -- options commonmark \ + --manpage-urls /tmp/manpage-urls.json \ + --revision nightly \ + result-hm/share/doc/nixos/options.json \ + /tmp/hm-raw.md + - name: Format to Markdown run: | python3 ./.github/scripts/generate-nix-options-docs.py \ - result-nixos/share/doc/nixos/options.json \ - result-hm/share/doc/nixos/options.json \ + /tmp/nixos-raw.md \ + /tmp/hm-raw.md \ docs/nix-options.md - name: Auto-commit changes diff --git a/docs/installation.md b/docs/installation.md index 903d7cb9..c5d4936c 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -202,7 +202,7 @@ The repository provides a Flake with a NixOS module. }; ``` - **Option B — Display manager autologin:** Autologin via an existing display manager (e.g. SDDM, GDM). [`addLoginEntry`](/docs/nix-module#addloginentry) (default: `true`) automatically registers mango as a session. + **Option B — Display manager autologin:** Autologin via an existing display manager (e.g. SDDM, GDM). [`addLoginEntry`](/docs/nix-options#addloginentry) (default: `true`) automatically registers mango as a session. ```nix services.displayManager = { @@ -240,7 +240,7 @@ The repository provides a Flake with a NixOS module. 5. **All available options** - See [Nix Module Options](/docs/nix-module) for the full list of NixOS and Home Manager options. + See [Nix Module Options](/docs/nix-options) for the full list of NixOS and Home Manager options. --- diff --git a/docs/nix-options.md b/docs/nix-options.md index 2a5d2038..2537d9d8 100644 --- a/docs/nix-options.md +++ b/docs/nix-options.md @@ -9,55 +9,163 @@ description: NixOS and Home Manager configuration options for mangowm. **System-level options via `programs.mango`.** -### `addLoginEntry` +### enable -Whether to add a login entry to the display manager for mango. Only has effect if a display manager is configured (e.g. SDDM, GDM via `services.displayManager`). -**Type:** `boolean` -**Default:** `true` +Whether to enable mango, a wayland compositor based on dwl\. ---- -### `enable` -Whether to enable mango, a wayland compositor based on dwl. +*Type:* +boolean -**Type:** `boolean` -**Default:** `false` -**Example:** `true` +*Default:* + +```nix +false +``` + + + +*Example:* + +```nix +true +``` + +*Declared by:* + - [\](https://github.com/mangowm/mango/blob/main/nix/nixos-modules.nix) + + + +### package ---- -### `package` The mango package to use -**Type:** `package` -**Default:** `` ---- +*Type:* +package + + + +*Default:* + +```nix + +``` + +*Declared by:* + - [\](https://github.com/mangowm/mango/blob/main/nix/nixos-modules.nix) + + + +### addLoginEntry + + + +Whether to add a login entry to the display manager for mango\. Only has effect if a display manager is configured (e\.g\. SDDM, GDM via ` services.displayManager `)\. + + + +*Type:* +boolean + + + +*Default:* + +```nix +true +``` + +*Declared by:* + - [\](https://github.com/mangowm/mango/blob/main/nix/nixos-modules.nix) ## Home Manager **Configure mangowm declaratively via `wayland.windowManager.mango`.** -### `autostart_sh` +### enable -Shell script to run on mango startup. No shebang needed. + + +Whether to enable mangowm, a Wayland compositor based on dwl\. + + + +*Type:* +boolean + + + +*Default:* + +```nix +false +``` + +*Declared by:* + - [\](https://github.com/mangowm/mango/blob/main/nix/hm-modules.nix) + + + +### package + + + +The mango package to use + + + +*Type:* +package + + + +*Default:* + +```nix + +``` + +*Declared by:* + - [\](https://github.com/mangowm/mango/blob/main/nix/hm-modules.nix) + + + +### autostart_sh + + + +Shell script to run on mango startup\. No shebang needed\. When this option is set, the script will be written to -`~/.config/mango/autostart.sh` and an `exec-once` line -will be automatically added to the config to execute it. +` ~/.config/mango/autostart.sh ` and an ` exec-once ` line +will be automatically added to the config to execute it\. -**Type:** `strings concatenated with "\n"` -**Default:** `""` -**Example:** +*Type:* +strings concatenated with “\\n” + + + +*Default:* + +```nix +"" +``` + + + +*Example:* + ```nix '' waybar & @@ -65,47 +173,71 @@ will be automatically added to the config to execute it. '' ``` ---- +*Declared by:* + - [\](https://github.com/mangowm/mango/blob/main/nix/hm-modules.nix) -### `bottomPrefixes` -List of prefixes for attributes that should appear at the bottom of the config file. -Attributes starting with these prefixes will be sorted to the end. -**Type:** `list of string` +### bottomPrefixes -**Default:** `[ ]` -**Example:** + +List of prefixes for attributes that should appear at the bottom of the config file\. +Attributes starting with these prefixes will be sorted to the end\. + + + +*Type:* +list of string + + + +*Default:* + +```nix +[ ] +``` + + + +*Example:* + ```nix [ "source" ] ``` ---- +*Declared by:* + - [\](https://github.com/mangowm/mango/blob/main/nix/hm-modules.nix) -### `enable` -Whether to enable mangowm, a Wayland compositor based on dwl. -**Type:** `boolean` +### extraConfig -**Default:** `false` ---- -### `extraConfig` +Extra configuration lines to add to ` ~/.config/mango/config.conf `\. +This is useful for advanced configurations that don’t fit the structured +settings format, or for options that aren’t yet supported by the module\. -Extra configuration lines to add to `~/.config/mango/config.conf`. -This is useful for advanced configurations that don't fit the structured -settings format, or for options that aren't yet supported by the module. -**Type:** `strings concatenated with "\n"` -**Default:** `""` +*Type:* +strings concatenated with “\\n” + + + +*Default:* + +```nix +"" +``` + + + +*Example:* -**Example:** ```nix '' # Advanced config that doesn't fit structured format @@ -113,38 +245,43 @@ settings format, or for options that aren't yet supported by the module. '' ``` ---- +*Declared by:* + - [\](https://github.com/mangowm/mango/blob/main/nix/hm-modules.nix) -### `package` -The mango package to use -**Type:** `package` +### settings -**Default:** `` ---- -### `settings` +Mango configuration written in Nix\. Entries with the same key +should be written as lists\. Variables and colors names should be +quoted\. See [https://mangowm\.github\.io/docs](https://mangowm\.github\.io/docs) for more examples\. -Mango configuration written in Nix. Entries with the same key -should be written as lists. Variables and colors names should be -quoted. See for more examples. +**Note:** This option uses a structured format that is converted to Mango’s +configuration syntax\. Nested attributes are flattened with underscore separators\. +For example: ` animation.duration_open = 400 ` becomes ` animation_duration_open = 400 ` -> **Note:** -> -> This option uses a structured format that is converted to Mango's -> configuration syntax. Nested attributes are flattened with underscore separators. -> For example: `animation.duration_open = 400` becomes `animation_duration_open = 400` -> -> Keymodes (submaps) are supported via the special `keymode` attribute. Each keymode -> is a nested attribute set under `keymode` that contains its own bindings. +Keymodes (submaps) are supported via the special ` keymode ` attribute\. Each keymode +is a nested attribute set under ` keymode ` that contains its own bindings\. -**Type:** `Mango configuration value` -**Default:** `{ }` -**Example:** +*Type:* +Mango configuration value + + + +*Default:* + +```nix +{ } +``` + + + +*Example:* + ```nix { # Window effects @@ -193,39 +330,72 @@ quoted. See for more examples. }; }; } + ``` ---- +*Declared by:* + - [\](https://github.com/mangowm/mango/blob/main/nix/hm-modules.nix) -### `systemd.enable` -Whether to enable `mango-session.target` on -mango startup. This links to -`graphical-session.target`. + +### systemd\.enable + + + +Whether to enable ` mango-session.target ` on +mango startup\. This links to +` graphical-session.target `\. Some important environment variables will be imported to systemd and dbus user environment before reaching the target, including -* `DISPLAY` -* `WAYLAND_DISPLAY` -* `XDG_CURRENT_DESKTOP` -* `XDG_SESSION_TYPE` -* `NIXOS_OZONE_WL` -You can extend this list using the `systemd.variables` option. -**Type:** `boolean` + - ` DISPLAY ` + - ` WAYLAND_DISPLAY ` + - ` XDG_CURRENT_DESKTOP ` + - ` XDG_SESSION_TYPE ` + - ` NIXOS_OZONE_WL ` + You can extend this list using the ` systemd.variables ` option\. -**Default:** `true` -**Example:** `false` ---- +*Type:* +boolean -### `systemd.extraCommands` -Extra commands to run after D-Bus activation. -**Type:** `list of string` +*Default:* + +```nix +true +``` + + + +*Example:* + +```nix +false +``` + +*Declared by:* + - [\](https://github.com/mangowm/mango/blob/main/nix/hm-modules.nix) + + + +### systemd\.extraCommands + + + +Extra commands to run after D-Bus activation\. + + + +*Type:* +list of string + + + +*Default:* -**Default:** ```nix [ "systemctl --user reset-failed" @@ -233,15 +403,26 @@ Extra commands to run after D-Bus activation. ] ``` ---- +*Declared by:* + - [\](https://github.com/mangowm/mango/blob/main/nix/hm-modules.nix) -### `systemd.variables` -Environment variables imported into the systemd and D-Bus user environment. -**Type:** `list of string` +### systemd\.variables + + + +Environment variables imported into the systemd and D-Bus user environment\. + + + +*Type:* +list of string + + + +*Default:* -**Default:** ```nix [ "DISPLAY" @@ -254,43 +435,85 @@ Environment variables imported into the systemd and D-Bus user environment. ] ``` -**Example:** + + +*Example:* + ```nix [ "--all" ] ``` ---- +*Declared by:* + - [\](https://github.com/mangowm/mango/blob/main/nix/hm-modules.nix) + + + +### systemd\.xdgAutostart + -### `systemd.xdgAutostart` Whether to enable autostart of applications using -`systemd-xdg-autostart-generator(8)`. +` systemd-xdg-autostart-generator(8) ` +\. -**Type:** `boolean` -**Default:** `false` -**Example:** `true` +*Type:* +boolean ---- -### `topPrefixes` -List of prefixes for attributes that should appear at the top of the config file. -Attributes starting with these prefixes will be sorted to the beginning. +*Default:* -**Type:** `list of string` +```nix +false +``` -**Default:** `[ ]` -**Example:** + +*Example:* + +```nix +true +``` + +*Declared by:* + - [\](https://github.com/mangowm/mango/blob/main/nix/hm-modules.nix) + + + +### topPrefixes + + + +List of prefixes for attributes that should appear at the top of the config file\. +Attributes starting with these prefixes will be sorted to the beginning\. + + + +*Type:* +list of string + + + +*Default:* + +```nix +[ ] +``` + + + +*Example:* + ```nix [ "source" ] ``` ---- +*Declared by:* + - [\](https://github.com/mangowm/mango/blob/main/nix/hm-modules.nix) diff --git a/nix/generate-options.nix b/nix/generate-options.nix index c2b87a4f..f8df3745 100644 --- a/nix/generate-options.nix +++ b/nix/generate-options.nix @@ -6,6 +6,9 @@ self: optionPrefix, }: let + # Absolute store path of the flake root, used to compute relative subpaths + repoPath = toString self; + eval = lib.evalModules { modules = [ (import module self) @@ -14,6 +17,15 @@ let specialArgs = { inherit pkgs; }; }; + # Relative path of the module file within the repo (e.g. "nix/hm-modules.nix") + moduleSubpath = lib.removePrefix "/" (lib.removePrefix repoPath (toString module)); + + # Declaration entry linking each option back to its source file on GitHub + moduleDeclaration = { + url = "https://github.com/mangowm/mango/blob/main/${moduleSubpath}"; + name = ""; + }; + optionsDoc = pkgs.nixosOptionsDoc { options = eval.options; transformOptions = @@ -21,7 +33,9 @@ let opt // { visible = opt.visible && !opt.internal; + # Strip the option prefix so docs show "enable" instead of "programs.mango.enable" name = lib.removePrefix optionPrefix opt.name; + declarations = [ moduleDeclaration ]; }; }; in