kapitan 0.36.2.dev6__tar.gz → 0.36.2.dev7__tar.gz

{kapitan-0.36.2.dev6 → kapitan-0.36.2.dev7}/.github/workflows/documentation.yml

@@ -46,10 +46,11 @@ jobs:
           uv run mike --version
           uv run mkdocs --version
 
-      - run: uv run mkdocs build
+      - name: Build docs (strict, timeout-guarded)
+        run: make docs_build
 
-      - name: Verify rendering
-        run: uv run pytest tests/test_docs_rendering.py -v --no-cov
+      - name: Verify rendering and flag-table generation
+        run: make docs_check
 
       # On master pushes (and manual dispatch): refresh the rolling "dev" docs.
       - name: Deploy dev docs

{kapitan-0.36.2.dev6 → kapitan-0.36.2.dev7}/Makefile

@@ -171,18 +171,31 @@ clean:
 # Documentation
 ################################################################################
 
-# Serve documentation locally for development
+# Build the documentation site once (what CI runs); fails if the build hangs.
+.PHONY: docs_build
+docs_build:
+	@echo "===== Building Documentation ====="
+	timeout 300 uv run mkdocs build --strict
+
+# Preview docs with live reload of LOCAL changes (unlike docs_serve / mike serve,
+# which only serves already-deployed versions from the gh-pages branch).
+.PHONY: docs_preview
+docs_preview:
+	@echo "===== Previewing Documentation (local changes) at http://localhost:8000 ====="
+	uv run mkdocs serve
+
+# Serve already-published documentation versions (mike / gh-pages)
 .PHONY: docs_serve
 docs_serve:
-	@echo "===== Serving Documentation Locally ====="
+	@echo "===== Serving Published Documentation Locally ====="
 	@echo "Documentation will be available at http://localhost:8000"
-	$(UV_RUN) mike serve
+	uv run mike serve
 
-# Verify fenced code blocks render correctly
+# Verify fenced code blocks render correctly + flag tables generate and build
 .PHONY: docs_check
 docs_check:
 	@echo "===== Verifying Documentation Rendering ====="
-	uv run pytest tests/test_docs_rendering.py -v --no-cov
+	uv run pytest tests/test_docs_rendering.py tests/test_docs_flags.py -v --no-cov
 	@echo "Documentation rendering verified!"
 
 # Deploy documentation to GitHub Pages
@@ -221,7 +234,10 @@ help:
 	@echo "  make test_docker        - Build and test Docker image"
 	@echo ""
 	@echo "Documentation:"
-	@echo "  make docs_serve         - Serve documentation locally"
+	@echo "  make docs_build         - Build docs once (--strict, timeout-guarded)"
+	@echo "  make docs_preview       - Live-preview LOCAL doc changes (mkdocs serve)"
+	@echo "  make docs_check         - Verify docs rendering + flag-table generation"
+	@echo "  make docs_serve         - Serve published versions (mike / gh-pages)"
 	@echo "  make docs_deploy        - Deploy docs to GitHub Pages"
 	@echo ""
 	@echo "Release Commands:"

{kapitan-0.36.2.dev6 → kapitan-0.36.2.dev7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kapitan
-Version: 0.36.2.dev6
+Version: 0.36.2.dev7
 Summary: Generic templated configuration management for Kubernetes, Terraform and other things
 Project-URL: Homepage, https://kapitan.dev
 Project-URL: Repository, https://github.com/kapicorp/kapitan

kapitan-0.36.2.dev7/docs/gen_flags.py

@@ -0,0 +1,159 @@
+# ruff: noqa: INP001 (docs/ is not an importable package; loaded via sys.path)
+"""Introspect Kapitan's argparse parser to generate flag-reference tables.
+
+Used at docs-build time by `markdown-exec` blocks so each command page and the
+`.kapitan` dotfile reference stay in sync with `kapitan/cli.py` automatically.
+There is no generated artifact to commit: the tables are rendered on every
+`mkdocs build` from the installed Kapitan, so they can never drift.
+
+Each public function *returns* a Markdown string (rather than printing it) so the
+calling exec block can `print()` it — markdown-exec only captures `print` calls
+made in the block's own namespace, not in imported helpers.
+"""
+
+import argparse
+
+from kapitan.cli import build_parser
+
+
+def _esc(value):
+    """Render a value as a single, table-safe Markdown cell."""
+    if value is None or value in ("", []):
+        return ""
+    if isinstance(value, (list | tuple)):
+        text = ", ".join(str(v) for v in value)
+    else:
+        text = str(value)
+    return " ".join(text.replace("|", "\\|").split())
+
+
+def _default_cell(value):
+    """Render a flag default as a code span. Lists become `["a", "b"]` rather
+    than a bare `a, b`, which reads ambiguously in a table cell."""
+    if value is None or value in ("", []):
+        return ""
+    if isinstance(value, (list | tuple)):
+        items = ", ".join(f'"{v}"' if isinstance(v, str) else str(v) for v in value)
+        text = f"[{items}]"
+    else:
+        text = str(value)
+    safe = " ".join(text.replace("|", "\\|").split())
+    return f"`{safe}`"
+
+
+def _subcommands(parser):
+    """Yield (name, subparser) for each subcommand, skipping alias duplicates."""
+    for action in parser._actions:
+        if isinstance(action, argparse._SubParsersAction):
+            seen = set()
+            for name, subparser in action.choices.items():
+                if id(subparser) in seen:
+                    continue  # alias of an already-emitted parser (e.g. `c` -> compile)
+                seen.add(id(subparser))
+                yield name, subparser
+
+
+def _flag_rows(parser):
+    """Yield dicts describing each user-facing argument of a parser."""
+    for action in parser._actions:
+        if isinstance(action, (argparse._HelpAction | argparse._SubParsersAction)):
+            continue
+        if action.option_strings == ["--version"] or isinstance(
+            action, argparse._VersionAction
+        ):
+            continue
+        opts = list(dict.fromkeys(action.option_strings))  # dedup, keep order
+        yield {
+            "options": ", ".join(f"`{o}`" for o in opts) or f"`{action.dest}`",
+            # dotfile key: long flag, dashes kept, leading -- stripped
+            "key": next(
+                (o.lstrip("-") for o in action.option_strings if o.startswith("--")),
+                action.dest,
+            ),
+            "positional": not action.option_strings,
+            "default": action.default,
+            "choices": list(action.choices) if action.choices else None,
+            "help": action.help,
+        }
+
+
+def _flag_table(rows):
+    """Return a Markdown flag table (or a placeholder when there are no flags)."""
+    flags = [r for r in rows if not r["positional"]]
+    if not flags:
+        return "_This command takes no optional flags._"
+    lines = ["| Flag | Default | Choices | Description |", "| --- | --- | --- | --- |"]
+    for r in flags:
+        lines.append(
+            f"| {r['options']} | {_default_cell(r['default'])} "
+            f"| {_esc(r['choices'])} | {_esc(r['help'])} |"
+        )
+    return "\n".join(lines)
+
+
+def _find_subparser(command):
+    for name, subparser in _subcommands(build_parser()):
+        if name == command:
+            return subparser
+    raise KeyError(f"unknown kapitan subcommand: {command!r}")
+
+
+def global_reference():
+    """Return the table of global flags accepted by every `kapitan` invocation."""
+    return _flag_table(list(_flag_rows(build_parser())))
+
+
+def command_reference(command):
+    """Return the flag table (and positional args) for a single subcommand."""
+    rows = list(_flag_rows(_find_subparser(command)))
+    positionals = [r for r in rows if r["positional"]]
+    parts = []
+    if positionals:
+        parts.append("**Arguments:** " + ", ".join(r["options"] for r in positionals))
+    parts.append(_flag_table(rows))
+    return "\n\n".join(parts)
+
+
+def _dotfile_table(rows):
+    """Return a `.kapitan` table (Key/Default/Description), or None if no flags."""
+    flags = [r for r in rows if not r["positional"]]
+    if not flags:
+        return None
+    lines = ["| Key | Default | Description |", "| --- | --- | --- |"]
+    for r in flags:
+        lines.append(
+            f"| `{r['key']}` | {_default_cell(r['default'])} | {_esc(r['help'])} |"
+        )
+    return "\n".join(lines)
+
+
+def dotfile_reference():
+    """Return Markdown `.kapitan` flag tables, one `###` section per command."""
+    parser = build_parser()
+    sections = [("global", list(_flag_rows(parser)))]
+    sections += [(name, list(_flag_rows(sub))) for name, sub in _subcommands(parser)]
+
+    out = []
+    for name, rows in sections:
+        table = _dotfile_table(rows)
+        if table is None:
+            continue  # e.g. deprecated `secrets` has no settable flags
+        out.append(f"### `{name}`\n\n{table}")
+    return "\n\n".join(out)
+
+
+if __name__ == "__main__":
+    # Invoked as a subprocess by the docs exec blocks so Kapitan's heavy imports
+    # (cloud SDKs, etc.) load in a short-lived process and never weigh down the
+    # mkdocs build process. Usage: gen_flags.py {global|dotfile|command <name>}
+    import sys
+
+    mode = sys.argv[1]
+    if mode == "global":
+        print(global_reference())
+    elif mode == "dotfile":
+        print(dotfile_reference())
+    elif mode == "command":
+        print(command_reference(sys.argv[2]))
+    else:
+        raise SystemExit(f"unknown mode: {mode!r}")

kapitan-0.36.2.dev7/docs/hooks.py

@@ -0,0 +1,40 @@
+# ruff: noqa: INP001 (docs/ is not an importable package; loaded by mkdocs as a hook)
+"""MkDocs build hook that injects auto-generated CLI flag tables.
+
+Pages drop a marker comment and this hook replaces it, at build time, with a
+Markdown table generated from Kapitan's argument parser (see `gen_flags.py`):
+
+    <!-- kapitan-flags:global -->            -> table of global flags
+    <!-- kapitan-flags:dotfile -->           -> per-section `.kapitan` tables
+    <!-- kapitan-flags:command:compile -->   -> flag table for one subcommand
+
+The generated Markdown is returned as page source, so it flows through the
+normal MkDocs pipeline exactly once. (An earlier `markdown-exec` version was
+dropped: re-rendering the output a second time made `pymdownx.inlinehilite`
+backtrack catastrophically on the many inline-code cells and hang the build.)
+"""
+
+import os
+import re
+import sys
+
+
+sys.path.insert(0, os.path.dirname(__file__))
+
+from gen_flags import command_reference, dotfile_reference, global_reference
+
+
+_MARKER = re.compile(r"<!--\s*kapitan-flags:(global|dotfile|command:[a-z]+)\s*-->")
+
+
+def _replace(match):
+    token = match.group(1)
+    if token == "global":
+        return global_reference()
+    if token == "dotfile":
+        return dotfile_reference()
+    return command_reference(token.split(":", 1)[1])
+
+
+def on_page_markdown(markdown, **kwargs):
+    return _MARKER.sub(_replace, markdown)

{kapitan-0.36.2.dev6 → kapitan-0.36.2.dev7}/docs/pages/commands/kapitan_compile.md

@@ -177,85 +177,8 @@ library), enabled with `--yaml-use-rapidyaml`.
       back to PyYAML for that single document (rapidyaml does not escape
       them in double-quoted scalars).
 
-## help
+## Flags
 
-!!! example ""
-
-    ```shell
-    kapitan compile --help
-    ```
+The table below is generated from **Kapitan**'s argument parser at docs-build time, so it always matches the installed version. See also the [global flags](kapitan_flags.md) accepted by every command, and the [`.kapitan` dotfile](kapitan_dotfile.md) to set any of these permanently.
 
-    ??? example "click to expand output"
-
-        ```shell
-        usage: kapitan compile [-h] [--inventory-backend {reclass}]
-                       [--search-paths JPATH [JPATH ...]]
-                       [--jinja2-filters FPATH] [--verbose] [--prune]
-                       [--quiet] [--output-path PATH] [--fetch]
-                       [--force-fetch] [--force] [--validate]
-                       [--parallelism INT] [--indent INT]
-                       [--refs-path REFS_PATH] [--reveal] [--embed-refs]
-                       [--inventory-path INVENTORY_PATH] [--cache]
-                       [--cache-paths PATH [PATH ...]]
-                       [--ignore-version-check] [--use-go-jsonnet]
-                       [--compose-target-name] [--schemas-path SCHEMAS_PATH]
-                       [--yaml-multiline-string-style STYLE]
-                       [--yaml-dump-null-as-empty]
-                       [--yaml-use-rapidyaml]
-                       [--targets TARGET [TARGET ...] | --labels
-                       [key=value ...]]
-
-        options:
-          -h, --help            show this help message and exit
-          --inventory-backend {reclass,reclass-rs}
-                                Select the inventory backend to use (default=reclass)
-          --search-paths JPATH [JPATH ...], -J JPATH [JPATH ...]
-                                set search paths, default is ["."]
-          --jinja2-filters FPATH, -J2F FPATH
-                                load custom jinja2 filters from any file, default is
-                                to put them inside lib/jinja2_filters.py
-          --verbose, -v         set verbose mode
-          --prune               prune jsonnet output
-          --quiet               set quiet mode, only critical output
-          --output-path PATH    set output path, default is "."
-          --fetch               fetch remote inventories and/or external dependencies
-          --force-fetch         overwrite existing inventory and/or dependency item
-          --force               overwrite existing inventory and/or dependency item
-          --validate            validate compile output against schemas as specified
-                                in inventory
-          --parallelism INT, -p INT
-                                Number of concurrent compile processes, default is
-                                min(len(targets), available CPU count)
-          --indent INT, -i INT  Indentation spaces for YAML/JSON, default is 2
-          --refs-path REFS_PATH
-                                set refs path, default is "./refs"
-          --reveal              reveal refs (warning: this will potentially write
-                                sensitive data)
-          --embed-refs          embed ref contents
-          --inventory-path INVENTORY_PATH
-                                set inventory path, default is "./inventory"
-          --cache, -c           enable compilation caching to $XDG_CACHE_HOME/kapitan,
-                                default is False [this is EXPERIMENTAL]
-          --cache-paths PATH [PATH ...]
-                                cache additional paths to .kapitan_cache, default is
-                                []
-          --ignore-version-check
-                                ignore the version from .kapitan
-          --use-go-jsonnet      use go-jsonnet
-          --compose-target-name   Create same subfolder structure from inventory/targets
-                                inside compiled folder
-          --schemas-path SCHEMAS_PATH
-                                set schema cache path, default is "./schemas"
-          --yaml-multiline-string-style STYLE, -L STYLE
-                                set multiline string style to STYLE, default is
-                                'double-quotes'
-          --yaml-dump-null-as-empty
-                                dumps all none-type entries as empty, default is
-                                dumping as 'null'
-          --yaml-use-rapidyaml  use the rapidyaml emitter, fallback to PyYaml
-                                if rapidyaml not installed, default is False.
-          --targets TARGET [TARGET ...], -t TARGET [TARGET ...]
-                                targets to compile, default is all
-          --labels [key=value ...], -l [key=value ...]
-                                compile targets matching the labels, default is all
-        ```
+<!-- kapitan-flags:command:compile -->

{kapitan-0.36.2.dev6 → kapitan-0.36.2.dev7}/docs/pages/commands/kapitan_dotfile.md

@@ -1,13 +1,15 @@
 ---
 title: "Kapitan .kapitan Dotfile: Override CLI Defaults"
-description: "Configure the .kapitan dotfile to pin versions and set persistent command flags across all Kapitan runs."
+description: "Configure the .kapitan dotfile (dot-kapitan) to pin versions and set persistent command flags across all Kapitan runs."
+search:
+  boost: 3
 ---
 
 # :kapitan-logo: **CLI Reference** | `.kapitan` config file
 
 ## `.kapitan`
 
-Kapitan allows you to coveniently override defaults by specifying a local `.kapitan` file in the root of your repository (relative to the kapitan configuration):
+Kapitan allows you to coveniently override defaults by specifying a local `.kapitan` file — also written **dot-kapitan** or **dot kapitan** — in the root of your repository (relative to the kapitan configuration):
 
 This comes handy to make sure **Kapitan** runs consistently for your specific setup.
 
@@ -75,4 +77,8 @@ which would be equivalent to always running **Kapitan** with `--inventory-backen
 
 Please note that the `inventory-backend` flag currently can't be set through the command-specific sections of the **Kapitan** config file.
 
-For additional entries in the `.kapitan` please search for `from_dot_kapitan` in the Kapitan source code.
+## Full flag reference
+
+The tables below are generated directly from **Kapitan**'s argument parser at docs-build time, so they always match the installed version. Each section maps to a top-level key in `.kapitan`: set a flag under the matching command, or under `global` to apply it to every command.
+
+<!-- kapitan-flags:dotfile -->

kapitan-0.36.2.dev7/docs/pages/commands/kapitan_eval.md

@@ -0,0 +1,16 @@
+---
+title: "Kapitan eval: Evaluate a Jsonnet File"
+description: "Run the kapitan eval command to evaluate a standalone Jsonnet file and print the result as YAML or JSON output."
+---
+
+# :kapitan-logo: **CLI Reference** | `kapitan eval`
+
+## `kapitan eval`
+
+Evaluates a standalone Jsonnet file and prints the result, without running a full compile. Useful for quickly testing Jsonnet snippets.
+
+## Flags
+
+The table below is generated from **Kapitan**'s argument parser at docs-build time, so it always matches the installed version. See also the [global flags](kapitan_flags.md) accepted by every command, and the [`.kapitan` dotfile](kapitan_dotfile.md) to set any of these permanently.
+
+<!-- kapitan-flags:command:eval -->

kapitan-0.36.2.dev7/docs/pages/commands/kapitan_flags.md

@@ -0,0 +1,16 @@
+---
+title: "Kapitan Global Flags: Options for Every Command"
+description: "Reference of the global Kapitan flags — multiprocessing, profiling, and memory options accepted by every command."
+---
+
+# :kapitan-logo: **CLI Reference** | Global flags
+
+These flags are accepted by **every** `kapitan` command (they sit before the
+subcommand, e.g. `kapitan --profile compile`). Each command also has its own
+flags — see the per-command pages — and any flag can be persisted in the
+[`.kapitan` dotfile](kapitan_dotfile.md).
+
+The table below is generated from **Kapitan**'s argument parser at docs-build
+time, so it always matches the installed version.
+
+<!-- kapitan-flags:global -->

kapitan-0.36.2.dev7/docs/pages/commands/kapitan_init.md

@@ -0,0 +1,16 @@
+---
+title: "Kapitan init: Generate a Project Skeleton"
+description: "Run the kapitan init command to scaffold a new Kapitan project skeleton from a Cruft or Copier template repository."
+---
+
+# :kapitan-logo: **CLI Reference** | `kapitan init`
+
+## `kapitan init`
+
+Scaffolds a new **Kapitan** project skeleton in the target directory from a Cruft/Copier template (the kapicorp reference repo by default).
+
+## Flags
+
+The table below is generated from **Kapitan**'s argument parser at docs-build time, so it always matches the installed version. See also the [global flags](kapitan_flags.md) accepted by every command, and the [`.kapitan` dotfile](kapitan_dotfile.md) to set any of these permanently.
+
+<!-- kapitan-flags:command:init -->

{kapitan-0.36.2.dev6 → kapitan-0.36.2.dev7}/docs/pages/commands/kapitan_inventory.md

@@ -194,3 +194,9 @@ For example, rendering the inventory for the `mysql` target:
           scripts: []
           target_name: mysql
         ```
+
+## Flags
+
+The table below is generated from **Kapitan**'s argument parser at docs-build time, so it always matches the installed version. See also the [global flags](kapitan_flags.md) accepted by every command, and the [`.kapitan` dotfile](kapitan_dotfile.md) to set any of these permanently.
+
+<!-- kapitan-flags:command:inventory -->

{kapitan-0.36.2.dev6 → kapitan-0.36.2.dev7}/docs/pages/commands/kapitan_lint.md

@@ -37,3 +37,9 @@ Perform a checkup on your inventory or refs.
         'features.gkms-demo',
         'projects.localhost.kubernetes.katacoda'}
         ```
+
+## Flags
+
+The table below is generated from **Kapitan**'s argument parser at docs-build time, so it always matches the installed version. See also the [global flags](kapitan_flags.md) accepted by every command, and the [`.kapitan` dotfile](kapitan_dotfile.md) to set any of these permanently.
+
+<!-- kapitan-flags:command:lint -->

kapitan-0.36.2.dev7/docs/pages/commands/kapitan_refs.md

@@ -0,0 +1,16 @@
+---
+title: "Kapitan refs: Manage Secret References"
+description: "Use the kapitan refs command to create, reveal, and manage encrypted secret references across all supported backends."
+---
+
+# :kapitan-logo: **CLI Reference** | `kapitan refs`
+
+## `kapitan refs`
+
+Creates, reveals, and manages encrypted secret references (`?{backend:path}`) backed by GPG, Vault, AWS/GCP KMS, Azure KeyVault and more.
+
+## Flags
+
+The table below is generated from **Kapitan**'s argument parser at docs-build time, so it always matches the installed version. See also the [global flags](kapitan_flags.md) accepted by every command, and the [`.kapitan` dotfile](kapitan_dotfile.md) to set any of these permanently.
+
+<!-- kapitan-flags:command:refs -->

{kapitan-0.36.2.dev6 → kapitan-0.36.2.dev7}/docs/pages/commands/kapitan_searchvar.md

@@ -43,3 +43,9 @@ Shows all inventory files where a variable is declared:
         ./inventory/classes/components/weaveworks/carts.yml          weaveworksdemos/carts:0.4.8
         ./inventory/classes/components/kapicorp/tesoro.yml           kapicorp/tesoro
         ```
+
+## Flags
+
+The table below is generated from **Kapitan**'s argument parser at docs-build time, so it always matches the installed version. See also the [global flags](kapitan_flags.md) accepted by every command, and the [`.kapitan` dotfile](kapitan_dotfile.md) to set any of these permanently.
+
+<!-- kapitan-flags:command:searchvar -->

kapitan-0.36.2.dev7/docs/stylesheets/extra.css

@@ -0,0 +1,8 @@
+/* Keep inline-code flag/key names (e.g. `--inventory-pool-cache`) from wrapping
+   mid-token inside the generated CLI flag tables. Wrapping still happens between
+   separate code spans and within the plain-text description column; tables that
+   overflow scroll horizontally as usual. */
+.md-typeset table:not([class]) td code,
+.md-typeset table:not([class]) th code {
+  white-space: nowrap;
+}

{kapitan-0.36.2.dev6 → kapitan-0.36.2.dev7}/mkdocs.yml

@@ -24,6 +24,12 @@ strict: true
 validation:
   links:
     not_found: ignore  # example links in code blocks (jinja.md compiled-result) are not real doc pages
+hooks:
+  - docs/hooks.py
+
+extra_css:
+  - stylesheets/extra.css
+
 plugins:
   - blog:
       archive: false
@@ -134,9 +140,13 @@ nav:
           - ArgoCD integration: pages/argocd.md
           - FluxCD integration: pages/fluxcd.md
       - CLI reference:
+          - global flags: pages/commands/kapitan_flags.md
           - compile: pages/commands/kapitan_compile.md
+          - eval: pages/commands/kapitan_eval.md
           - inventory: pages/commands/kapitan_inventory.md
+          - init: pages/commands/kapitan_init.md
           - lint: pages/commands/kapitan_lint.md
+          - refs: pages/commands/kapitan_refs.md
           - searchvar: pages/commands/kapitan_searchvar.md
           - validate: pages/commands/kapitan_validate.md
           - kapitan dotfile: pages/commands/kapitan_dotfile.md