Add more diagrams

Author: kdeldycke

changelog.md

@@ -5,7 +5,7 @@
 > [!WARNING]
 > This version is **not released yet** and is under active development.
 
-- Add Mermaid diagrams to the configuration documentation. A new "Resolving a configuration file" section charts how a config source is selected (explicit `--config` versus autodiscovery, CWD `pyproject.toml` search, app-dir glob, first parseable file wins), and the "Precedence" section now renders the value-resolution chain (interactive prompt, CLI parameters, environment variables, configuration file, defaults) as a flowchart instead of a nested list.
+- Add Mermaid diagrams throughout the documentation to render resolution and layering rules previously carried by prose or nested lists: configuration-file source selection and value precedence (`config.md`), the Click / Cloup / click-extra class layering and the `@command`/`@group` default-option bundle (`commands.md`), `--color`/`--no-color` ANSI enablement (`colorize.md`), the `{version}` and `{exec_name}` fallback chains (`version.md`), the `decorator_factory` subclass guardrail (`decorators.md`), and environment-variable id resolution (`envvar.md`).
 
 ## [`7.17.1` (2026-05-25)](https://github.com/kdeldycke/click-extra/compare/v7.17.0...v7.17.1)
 

docs/colorize.md

@@ -215,6 +215,21 @@ Click Extra adds a `--color`/`--no-color` flag (aliased as `--ansi`/`--no-ansi`)
 
 The option respects the [`NO_COLOR`](https://no-color.org), `CLICOLOR`, and `CLICOLOR_FORCE` environment variables. When any of these signals "no color", the environment takes precedence over the default value (but an explicit `--color` or `--no-color` on the command line always wins).
 
+```mermaid
+:align: center
+
+flowchart TD
+    start(["echo() must decide: emit ANSI codes?"]) --> cli{"--color / --no-color<br/>set on CLI or via config?"}
+    cli -->|yes| useflag["use that value"]
+    cli -->|"no (built-in default)"| env{"a recognized color env var set?<br/>NO_COLOR, CLICOLOR, CLICOLOR_FORCE,<br/>FORCE_COLOR, LLM, ..."}
+    env -->|yes| envval["ON if any signals color,<br/>OFF otherwise"]
+    env -->|no| deflt["default: color ON"]
+    useflag --> ctxcolor(["ctx.color"])
+    envval --> ctxcolor
+    deflt --> ctxcolor
+    ctxcolor --> strip["echo() strips ANSI when OFF;<br/>NO_COLOR also blanks --theme output"]
+```
+
 All Click Extra commands and groups include this option by default. Use `color_option` as a standalone decorator when building CLIs with plain `click.command`:
 
 ```{click:source}

docs/commands.md

@@ -12,6 +12,43 @@ At the module level, `click_extra` imports all elements from `click.*`, then all
 
 Which means all elements not redefined by Click Extra fallback to Cloup. And if Cloup itself does not redefine them, they fallback to Click.
 
+For the types Click Extra does re-implement, each subclasses its Cloup counterpart, which in turn subclasses Click's (arrows point from a child to the parent it inherits from):
+
+```mermaid
+:align: center
+
+flowchart TB
+    subgraph CE["click_extra (extends and overrides)"]
+        direction LR
+        XCmd["ExtraCommand"]
+        XGrp["ExtraGroup"]
+        XOpt["Option"]
+        XCtx["ExtraContext"]
+        XSty["Style"]
+    end
+    subgraph CL["cloup (first fallback)"]
+        direction LR
+        CCmd["cloup.Command"]
+        CGrp["cloup.Group"]
+        COpt["cloup.Option"]
+        CCtx["cloup.Context"]
+        CSty["cloup.Style"]
+    end
+    subgraph CK["click (base)"]
+        direction LR
+        KCmd["click.Command"]
+        KGrp["click.Group"]
+        KOpt["click.Option"]
+        KCtx["click.Context"]
+        KSty["click.style()"]
+    end
+    XCmd --> CCmd --> KCmd
+    XGrp --> CGrp --> KGrp
+    XOpt --> COpt --> KOpt
+    XCtx --> CCtx --> KCtx
+    XSty --> CSty -.->|wraps| KSty
+```
+
 For example:
 
 - `click_extra.echo` is a direct alias to `click.echo` because neither Click Extra or Cloup re-implements an `echo` helper.
@@ -77,7 +114,29 @@ You can inspect the implementation details in:
 
 ## Default options
 
-The `@command` and `@group` decorators are pre-configured with a set of {py:func}`default options <click_extra.commands.default_extra_params>`.
+The `@command` and `@group` decorators are pre-configured with a set of {py:func}`default options <click_extra.commands.default_extra_params>`. The `--help`/`-h` option is added separately through `help_option_names`, which is why it survives even when `default_extra_params()` is reset:
+
+```mermaid
+:align: center
+
+flowchart LR
+    cmd(["@command / @group"]) --> params
+    cmd --> help["--help / -h"]
+    subgraph params["default_extra_params()"]
+        direction TB
+        opt1["--time / --no-time"]
+        opt2["--config"]
+        opt3["--no-config"]
+        opt4["--validate-config"]
+        opt5["--color / --no-color"]
+        opt6["--theme"]
+        opt7["--show-params"]
+        opt8["--table-format"]
+        opt9["--verbosity"]
+        opt10["--verbose / -v"]
+        opt11["--version"]
+    end
+```
 
 ```{tip}
 Each default option publishes its resolved value on `ctx.meta` so you can pick it up from anywhere in your CLI. See the [available keys](context.md#available-keys) table for the full inventory and worked examples.

docs/decorators.md

@@ -30,6 +30,21 @@ group = decorator_factory(
 )
 ```
 
+```mermaid
+:align: center
+
+flowchart TD
+    call(["@command / @option(...)<br/>possibly with cls=Custom"]) --> paren{"called with<br/>or without parens?"}
+    paren -->|"@command"| norm["allow_missing_parenthesis<br/>normalizes both call forms"]
+    paren -->|"@command()"| norm
+    norm --> has{"user passed cls= ?"}
+    has -->|no| build["use the factory's default cls<br/>(ExtraCommand / ExtraGroup / ...)"]
+    has -->|yes| sub{"cls subclasses<br/>the factory's cls?"}
+    sub -->|yes| build
+    sub -->|no| err["raise TypeError<br/>with the full MRO listing"]
+    build --> out["decorator with merged defaults<br/>and a fresh params() list"]
+```
+
 After that wiring, `@command` always produces an `ExtraCommand`, and `@command(cls=MyExtraCommand)` is accepted *only if* `MyExtraCommand` is a subclass of `ExtraCommand`. Anything else raises a `TypeError` with a full MRO listing of the offending class, so the caller sees *why* their override was rejected:
 
 ```{python:run}

docs/envvar.md

@@ -77,6 +77,16 @@ with click.Context(show) as ctx:
 
 Returns the deduplicated, ordered tuple of environment variables Click would consider for an option or argument: the user-declared `envvar=` value (single string or iterable) followed by the auto-generated one. Click reads them in this order and stops at the first one set, which means **user-declared envvars take precedence over the auto-generated one** — `param_envvar_ids` preserves that ordering.
 
+```mermaid
+:align: center
+
+flowchart LR
+    decl["param.envvar<br/>user-declared:<br/>string or nested iterable"] --> merge
+    auto["param_auto_envvar_id()<br/>PREFIX_NAME,<br/>if auto-envvar enabled"] --> merge
+    merge["merge_envvar_ids()<br/>flatten, drop empty,<br/>dedupe, upper-case on Windows"] --> tup["ordered tuple<br/>user-declared first,<br/>auto-generated last"]
+    tup --> reader["Click reads in order,<br/>stops at first set<br/>so user-declared wins"]
+```
+
 ```{python:run}
 import click
 

docs/version.md

@@ -97,6 +97,25 @@ The `{version}` variable is resolved in this order:
 4. `None` if none of the above succeeds (e.g. unpackaged scripts without `__version__`).
 ```
 
+Both `{exec_name}` and `{version}` are derived through a short fallback chain (`{version}` additionally appends the Git short hash for `.dev` builds):
+
+```mermaid
+:align: center
+
+flowchart TD
+    subgraph EXEC["exec_name"]
+        direction TB
+        x1["module name"] -->|"is __main__"| x2["package name"]
+        x2 -->|"not packaged"| x3["script filename"]
+    end
+    subgraph VER["version"]
+        direction TB
+        m["module __version__"] -->|unset| p["package metadata"]
+        p -->|unset| nil["None"]
+    end
+    VER -.->|"if .dev without +local, and git available"| gh["append the Git short hash<br/>e.g. 1.2.3.dev0+abc1234"]
+```
+
 ```{error}
 Some Click's built-in variables are not recognized:
 - `%(package)s` should be replaced by `{package_name}`