Reconcile docs and man_page module for release

Point the `@timer_option` / `--time` cross-reference links in
`tutorial.md` and `benchmark.md` at `execution.md#timer`: the
`#execution-time` heading disappeared when the `jobs` and `timer`
modules were consolidated into `execution`. Fix `commands.md` to name
the real `@click_extra.timer_option` export instead of the
non-existent `@click_extra.timer`.

Tidy `click_extra/man_page.py`: read package metadata by subscript so
the author lookup type-checks, coalesce the root command's `info_name`
to a string to honor the `tuple[str, ...]` return contract, and
document the best-effort `except` in `_resolve_files`.

Reorder the changelog so `--accessible` sits beside `--man` among the
`@extra_command` default-option additions.

Co-Authored-By: Claude <noreply@anthropic.com>

Author: kdeldycke

changelog.md

@@ -6,12 +6,12 @@
 > This version is **not released yet** and is under active development.
 
 - Add a `--man` option to the default set of `@extra_command` and `@extra_group` (via `default_extra_params()`): it prints the command's man page (roff) to stdout and exits. Also available as the `@man_option` decorator for plain Click CLIs.
+- Add an `--accessible` option to the default set of `@extra_command` and `@extra_group` (via `default_extra_params()`). Enabling it, or setting the `ACCESSIBLE` environment variable, is equivalent to `--no-color --table-format plain`: it strips ANSI codes and renders tables without Unicode box-drawing characters, for screen readers. An explicit `--color` or `--table-format` (on the command line or in a configuration file) keeps precedence. Also available as the `@accessible_option` decorator and the `AccessibleOption` class.
 - Add a `man` subcommand to the `click-extra` CLI: `click-extra man SCRIPT [SUBCOMMAND]...` renders the man page (roff) of any external Click CLI without running it, resolving the target like `show-params` (console_scripts entry point, `module:function` notation, `.py` file, or module name). Both subcommands now also load `.py` file targets, which previously raised an unhandled error.
 - Generate man pages programmatically with the new `click_extra.man_page` module: `render_manpage()` for a single command, `render_manpages()` for the whole command tree (one page per subcommand), and `write_manpages()` to write `.1` files (handy from a Debian `override_dh_installman` rule). Pages follow the man-pages(7) layout, discover subcommands dynamically, honor Click's `\b` no-rewrap marker and `SOURCE_DATE_EPOCH` for reproducible builds, and mirror Cloup option groups as `.SS` subsections (ungrouped options fall under an `Other options` heading).
 - Add a pre-configured `-0`/`--zero-exit` option flag, exposed as the `@zero_exit_option` decorator and the `ZeroExitOption` class. It stores the user's intent in `ctx.meta` under the new `ZERO_EXIT` key but does not alter the exit code itself: downstream code reads it to decide whether to suppress its non-zero "problems found" status.
 - Consolidate the `--time`, `--jobs` and `-0`/`--zero-exit` options into a single `click_extra.execution` module. The `click_extra.jobs` and `click_extra.timer` submodules are removed: their decorators and classes (`timer_option`, `jobs_option`, `TimerOption`, `JobsOption`, `CPU_COUNT`, `DEFAULT_JOBS`) remain importable from the `click_extra` root. The `--show-params` table now reports these options under `click_extra.execution`.
 - Honor the standard `POSIXLY_CORRECT` environment variable. When it is present in the environment (regardless of value), `ExtraContext` forces `allow_interspersed_args` to `False`, so every Click Extra command and group stops parsing options at the first positional argument, matching GNU getopt-based tools.
-- Add an `--accessible` option to the default set of `@extra_command` and `@extra_group` (via `default_extra_params()`). Enabling it, or setting the `ACCESSIBLE` environment variable, is equivalent to `--no-color --table-format plain`: it strips ANSI codes and renders tables without Unicode box-drawing characters, for screen readers. An explicit `--color` or `--table-format` (on the command line or in a configuration file) keeps precedence. Also available as the `@accessible_option` decorator and the `AccessibleOption` class.
 - Add the `run_config_validation()` function and the `ValidationReport` dataclass to `click_extra.config` (both re-exported from the package root). They run the CLI-parameter strict check, the typed schema build, and every registered `ConfigValidator` in a single pass, returning the typed schema instance, the extracted extension sub-trees, and the list of `ValidationError`s. `collect_all=True` gathers every error; `collect_all=False` stops at the first. Both `--validate-config` and normal `--config` loading now delegate to this primitive.
 - Unify configuration-loading errors under the single `ValidationError` type. Unknown CLI-parameter keys (`strict=True`) and unknown schema fields (`schema_strict=True`) previously surfaced as an uncaught `ValueError` traceback during `--config` loading; they now stop the run with a critical-level log and exit code 1, the same failure mode as extension-validator errors. Code that caught `ValueError` from config loading should catch the `SystemExit` from the exit (or use `--validate-config` / `run_config_validation()` to inspect errors without exiting).
 - Fix `schema_strict=True` wrongly rejecting the contents of a configuration field marked as an extension point with `EXTENSION_METADATA_KEY` when the field's Python type is not a mapping. The dataclass adapter now honors the marker the same way the outer strict check does, so the marked sub-tree is kept intact instead of being flattened and reported as unknown keys.

click_extra/man_page.py

@@ -438,7 +438,7 @@ def _resolve_authors(ctx: Context) -> str | None:
             meta = metadata.metadata(name)
         except metadata.PackageNotFoundError:
             continue
-        author = meta.get("Author") or meta.get("Author-email")
+        author = meta["Author"] or meta["Author-email"]
         if author:
             return author
     return None
@@ -465,7 +465,9 @@ def _resolve_files(command: Command, ctx: Context) -> tuple[str, ...]:
                 default = _config_default(config_option, ctx)
         else:
             default = _config_default(config_option, ctx)
-    except Exception:
+    # FILES is an optional section: any failure resolving the search pattern
+    # (missing context, app-dir lookup errors, …) just drops it silently.
+    except Exception:  # noqa: BLE001
         return ()
     if not default or default in ("disabled", "None"):
         return ()
@@ -616,7 +618,7 @@ def iter_command_contexts(
     ``resilient_parsing=True`` to avoid triggering required-argument errors,
     prompts, or eager-option side effects.
     """
-    info_name = (prog_name or command.name) if not _path else (command.name or "")
+    info_name = (prog_name or command.name or "") if not _path else (command.name or "")
     ctx = command.make_context(
         info_name, [], parent=_parent, resilient_parsing=True
     )

docs/benchmark.md

@@ -31,7 +31,7 @@ Feature comparison between Click Extra and competing CLI frameworks across ecosy
 | Telemetry control         |       ✓       |             |             |             |            |             |            |              |       ~        |            |         ~         |             |
 | Version with git metadata |       ✓       |      ~      |      ~      |             |            |      ~      |            |              |       ~        |            |         ~         |             |
 
-click-extra's [colored help](colorize.md) uses [a theme system](theme.md) with semantic highlighting for options, choices, metavars, defaults, env vars, and subcommand names. [Seven built-in themes](theme.md#built-in-themes) ship out of the box (`dark`, `light`, `dracula`, `monokai`, `nord`, `solarized_dark`, plus a monochrome `manpage`); users can [override any slot of an existing palette or define brand-new themes directly in the CLI's `--config` file](theme.md#themes-from-your-config-file) (`[tool.<cli>.themes.<name>]`), with overrides scoped per-invocation so concurrent runs in the same process don't bleed into each other. cobra only provides basic ANSI coloring. rich-click and Cyclopts use Rich for formatted help output but ship a single style; user-defined palettes require Python code. Shell completion in Click and click-extra covers command and option names; clap, cobra, bpaf, Cyclopts, and Typer add dynamic value completion and multi-shell auto-install. click-extra also offers [`--show-params`](parameters.md#show-params-option), [`--time`](execution.md#execution-time), [`--telemetry`/`--no-telemetry`](telemetry.md), [`--table-format`](table.md), and [git-aware `--version`](version.md) out of the box.
+click-extra's [colored help](colorize.md) uses [a theme system](theme.md) with semantic highlighting for options, choices, metavars, defaults, env vars, and subcommand names. [Seven built-in themes](theme.md#built-in-themes) ship out of the box (`dark`, `light`, `dracula`, `monokai`, `nord`, `solarized_dark`, plus a monochrome `manpage`); users can [override any slot of an existing palette or define brand-new themes directly in the CLI's `--config` file](theme.md#themes-from-your-config-file) (`[tool.<cli>.themes.<name>]`), with overrides scoped per-invocation so concurrent runs in the same process don't bleed into each other. cobra only provides basic ANSI coloring. rich-click and Cyclopts use Rich for formatted help output but ship a single style; user-defined palettes require Python code. Shell completion in Click and click-extra covers command and option names; clap, cobra, bpaf, Cyclopts, and Typer add dynamic value completion and multi-shell auto-install. click-extra also offers [`--show-params`](parameters.md#show-params-option), [`--time`](execution.md#timer), [`--telemetry`/`--no-telemetry`](telemetry.md), [`--table-format`](table.md), and [git-aware `--version`](version.md) out of the box.
 
 ## Parser flag scoping
 

docs/commands.md

@@ -53,7 +53,7 @@ For example:
 
 - `click_extra.echo` is a direct alias to `click.echo` because neither Click Extra or Cloup re-implements an `echo` helper.
 - [`@cloup.option_group` is a specific feature of Cloup](https://cloup.readthedocs.io/en/stable/pages/option-groups.html) that is only implemented by it. It is not modified by Click Extra, and Click does not implement it. Still, `@click_extra.option_group` is a direct alias to Cloup's one.
-- `@click_extra.timer` is a new decorator only implemented by Click Extra. So it is not a proxy of anything.
+- `@click_extra.timer_option` is a new decorator only implemented by Click Extra. So it is not a proxy of anything.
 - As for `@click_extra.version_option`, it is a re-implementation of `@click.version_option`, and so overrides it. If you want to use its original version, import it directly from `click` namespace.
 
 Here is some of the main decorators of Click Extra and how they wraps and extends Cloup and Click ones:

docs/tutorial.md

@@ -219,7 +219,7 @@ Click Extra provides these additional, pre-configured options decorators you can
 
 | Decorator                                                          | Specification                             | Default |
 | ------------------------------------------------------------------ | ----------------------------------------- | ------- |
-| [`@timer_option`](execution.md#execution-time)                     | `--time / --no-time`                      | ✅      |
+| [`@timer_option`](execution.md#timer)                              | `--time / --no-time`                      | ✅      |
 | [`@accessible_option`](colorize.md#accessible-flag)                | `--accessible`                            | ✅      |
 | [`@color_option`](colorize.md#color-no-color-flag)                 | `--color, --ansi / --no-color, --no-ansi` | ✅      |
 | [`@theme_option`](theme.md)                                        | `--theme`                                 | ✅      |

tests/test_man_page.py

@@ -276,6 +276,7 @@ def test_generated_roff_passes_groff_lint(cli, prog_name):
             input=roff,
             capture_output=True,
             text=True,
+            check=False,
         )
         assert proc.returncode == 0, f"{filename}: {proc.stderr}"
         assert not proc.stderr.strip(), f"{filename}: {proc.stderr}"