Skip to content

Commit e879a79

Browse files
kdeldyckegithub-actions[bot]
kdeldycke
authored and
github-actions[bot]
committed
[autofix] Format Markdown
1 parent 83e5dda commit e879a79

File tree

14 files changed

+621
-318
lines changed

14 files changed

+621
-318
lines changed

‎changelog.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -80,7 +80,7 @@
8080
## [6.0.0 (2025-09-25)](https://github.com/kdeldycke/click-extra/compare/v5.1.1...v6.0.0)
8181

8282
- Add new variables for version string template: `{git_repo_path}`, `{git_branch}`, `{git_long_hash}`, `{git_short_hash}` and `{git_date}`.
83-
- Add a new `--no-config` option on `@extra_command` and `@extra_group` to disable configuration files. Closes {issue}`750`.
83+
- Add a new `--no-config` option on `@extra_command` and `@extra_group` to disable configuration files. Closes {issue}`750`.
8484
- Add `--table-format` option by default on `@extra_command` and `@extra_group`.
8585
- Let `--table-format` and `--no-color` affect the rendering of `--show-params` table.
8686
- Swap `Class` and `Spec.` columns in `--show-params` output.

‎docs/changelog.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,4 +4,4 @@
44
---
55
start-line: 2
66
---
7-
```
7+
```

‎docs/commands.md‎

Lines changed: 73 additions & 52 deletions
Original file line numberDiff line numberDiff line change
@@ -13,58 +13,59 @@ At the module level, `click_extra` imports all elements from `click.*`, then all
1313
Which means all elements not redefined by Click Extra fallback to Cloup. And if Cloup itself does not redefine them, they fallback to Click.
1414

1515
For example:
16+
1617
- `click_extra.echo` is a direct alias to `click.echo` because neither Click Extra or Cloup re-implements an `echo` helper.
1718
- [`@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.
1819
- `@click_extra.timer` is a new decorator only implemented by Click Extra. So it is not a proxy of anything.
1920
- 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.
2021

2122
Here is some of the main decorators of Click Extra and how they wraps and extends Cloup and Click ones:
2223

23-
| Decorators from `click_extra` | Wrapped decorator | Base class |
24-
| :--------------------------------- | :----------------------- | :----------------------------------- |
25-
| `@command` | `@cloup.command` | `click_extra.ExtraCommand` |
26-
| `@group` | `@cloup.group` | `click_extra.ExtraGroup` |
27-
| `@lazy_group` | `@click_extra.group` | `click_extra.LazyGroup` |
28-
| `@option` | `@cloup.option` | `click_extra.Option` |
29-
| `@argument` | `@cloup.argument` | `click_extra.Argument` |
30-
| `@version_option` | `@click_extra.option` | `click_extra.ExtraVersionOption` |
31-
| `@color_option` | `@click_extra.option` | `click_extra.ColorOption` |
32-
| `@config_option` | `@click_extra.option` | `click_extra.ConfigOption` |
33-
| `@no_config_option` | `@click_extra.option` | `click_extra.NoConfigOption` |
34-
| `@show_params_option` | `@click_extra.option` | `click_extra.ShowParamsOption` |
35-
| `@table_format_option` | `@click_extra.option` | `click_extra.TableFormatOption` |
36-
| `@telemetry_option` | `@click_extra.option` | `click_extra.TelemetryOption` |
37-
| `@timer_option` | `@click_extra.option` | `click_extra.TimerOption` |
38-
| `@verbose_option` | `@click_extra.option` | `click_extra.VerboseOption` |
39-
| `@verbosity_option` | `@click_extra.option` | `click_extra.VerbosityOption` |
40-
| `@option_group` | `@cloup.option_group` | `cloup.OptionGroup` |
41-
| `@pass_context` | `@click.pass_context` | - |
42-
| `@help_option` | `@click.help_option` | - |
43-
| … | … | … |
24+
| Decorators from `click_extra` | Wrapped decorator | Base class |
25+
| :---------------------------- | :-------------------- | :------------------------------- |
26+
| `@command` | `@cloup.command` | `click_extra.ExtraCommand` |
27+
| `@group` | `@cloup.group` | `click_extra.ExtraGroup` |
28+
| `@lazy_group` | `@click_extra.group` | `click_extra.LazyGroup` |
29+
| `@option` | `@cloup.option` | `click_extra.Option` |
30+
| `@argument` | `@cloup.argument` | `click_extra.Argument` |
31+
| `@version_option` | `@click_extra.option` | `click_extra.ExtraVersionOption` |
32+
| `@color_option` | `@click_extra.option` | `click_extra.ColorOption` |
33+
| `@config_option` | `@click_extra.option` | `click_extra.ConfigOption` |
34+
| `@no_config_option` | `@click_extra.option` | `click_extra.NoConfigOption` |
35+
| `@show_params_option` | `@click_extra.option` | `click_extra.ShowParamsOption` |
36+
| `@table_format_option` | `@click_extra.option` | `click_extra.TableFormatOption` |
37+
| `@telemetry_option` | `@click_extra.option` | `click_extra.TelemetryOption` |
38+
| `@timer_option` | `@click_extra.option` | `click_extra.TimerOption` |
39+
| `@verbose_option` | `@click_extra.option` | `click_extra.VerboseOption` |
40+
| `@verbosity_option` | `@click_extra.option` | `click_extra.VerbosityOption` |
41+
| `@option_group` | `@cloup.option_group` | `cloup.OptionGroup` |
42+
| `@pass_context` | `@click.pass_context` | - |
43+
| `@help_option` | `@click.help_option` | - |
44+
| … | … | … |
4445

4546
Same for the main classes and functions, where some are re-implemented by Click Extra, and others are direct aliases to Cloup or Click ones:
4647

47-
| Classes from `click_extra` | Alias to | Parent class |
48-
| :------------------------------- | :------------------------------ | :--------------------------- |
49-
| `ExtraCommand` | - | `cloup.Command` |
50-
| `ExtraGroup` | - | `cloup.Group` |
51-
| `LazyGroup` | - | `click_extra.ExtraGroup` |
52-
| `Option` | - | `cloup.Option` |
53-
| `Argument` | - | `cloup.Argument` |
54-
| `ExtraContext` | - | `cloup.Context` |
55-
| `HelpFormatter` | `cloup.HelpFormatter` | |
56-
| `HelpExtraFormatter` | - | `cloup.HelpFormatter` |
57-
| `HelpTheme` | `cloup.HelpThene` | |
58-
| `HelpExtraTheme` | - | `cloup.HelpThene` |
59-
| `ExtraCliRunner` | - | `click.testing.CliRunner` |
60-
| `ExtraVersionOption` | - | |
61-
| `Style` | `cloup.Style` | |
62-
| `echo` | `click.echo` | |
63-
| `ParameterSource` | `click.core.ParameterSource` | |
64-
| `UNSET` | `click._utils.UNSET` | |
65-
| `Choice` | `click.Choice` | |
66-
| `EnumChoice` | - | `click.Choice` |
67-
| … | … | … |
48+
| Classes from `click_extra` | Alias to | Parent class |
49+
| :------------------------- | :--------------------------- | :------------------------ |
50+
| `ExtraCommand` | - | `cloup.Command` |
51+
| `ExtraGroup` | - | `cloup.Group` |
52+
| `LazyGroup` | - | `click_extra.ExtraGroup` |
53+
| `Option` | - | `cloup.Option` |
54+
| `Argument` | - | `cloup.Argument` |
55+
| `ExtraContext` | - | `cloup.Context` |
56+
| `HelpFormatter` | `cloup.HelpFormatter` | |
57+
| `HelpExtraFormatter` | - | `cloup.HelpFormatter` |
58+
| `HelpTheme` | `cloup.HelpThene` | |
59+
| `HelpExtraTheme` | - | `cloup.HelpThene` |
60+
| `ExtraCliRunner` | - | `click.testing.CliRunner` |
61+
| `ExtraVersionOption` | - | |
62+
| `Style` | `cloup.Style` | |
63+
| `echo` | `click.echo` | |
64+
| `ParameterSource` | `click.core.ParameterSource` | |
65+
| `UNSET` | `click._utils.UNSET` | |
66+
| `Choice` | `click.Choice` | |
67+
| `EnumChoice` | - | `click.Choice` |
68+
| … | … | … |
6869

6970
```{hint}
7071
You can inspect the implementation details in:
@@ -83,7 +84,9 @@ The `@command` and `@group` decorators are [pre-configured with a set of default
8384
You can remove all default options by resetting the `params` argument to `None`:
8485

8586
```{click:example}
86-
:emphasize-lines: 3
87+
---
88+
emphasize-lines: 3
89+
---
8790
from click_extra import command
8891
8992
@command(params=None)
@@ -113,7 +116,9 @@ As you can see, all options are stripped out, but the colouring and formatting o
113116
To override the default options, you can provide the `params=` argument to the command. But note how we use classes instead of option decorators:
114117

115118
```{click:example}
116-
:emphasize-lines: 4-7
119+
---
120+
emphasize-lines: 4-7
121+
---
117122
from click_extra import command, ConfigOption, VerbosityOption
118123
119124
@command(
@@ -129,7 +134,9 @@ def cli():
129134
And now you get:
130135

131136
```{click:run}
132-
:emphasize-lines: 5-9
137+
---
138+
emphasize-lines: 5-9
139+
---
133140
from textwrap import dedent
134141
result = invoke(cli, args=["--help"])
135142
assert result.stdout.startswith(dedent(
@@ -144,7 +151,9 @@ assert result.stdout.startswith(dedent(
144151
This let you replace the preset options by your own set, tweak their order and fine-tune their defaults.
145152

146153
````{admonition} Duplicate options
147-
:class: caution
154+
---
155+
class: caution
156+
---
148157
If you try to add option decorators to a command which already have them by default, you will end up with duplicate entries ([as seen in issue #232](https://github.com/kdeldycke/click-extra/issues/232)):
149158
150159
```{click:example}
@@ -194,7 +203,9 @@ For example, the [`--verbosity` option defaults to the `WARNING` level](logging.
194203
If you manage your own `--verbosity` option, you can [pass the `default` argument to its decorator like we did above](#change-default-options):
195204

196205
```{click:example}
197-
:emphasize-lines: 2,5
206+
---
207+
emphasize-lines: 2,5
208+
---
198209
import click
199210
from click_extra import verbosity_option
200211
@@ -207,7 +218,9 @@ def cli():
207218
This also works in its class form:
208219

209220
```{click:example}
210-
:emphasize-lines: 2,4
221+
---
222+
emphasize-lines: 2,4
223+
---
211224
import click
212225
from click_extra import VerbosityOption
213226
@@ -219,7 +232,9 @@ def cli():
219232
With a `@click_extra.command` instead of `@click.command`, it is the same, you also have the alternative to pass a `default_map` via the `context_settings`:
220233

221234
```{click:example}
222-
:emphasize-lines: 1,3
235+
---
236+
emphasize-lines: 1,3
237+
---
223238
import click_extra
224239
225240
@click_extra.command(context_settings={"default_map": {"verbosity": "INFO"}})
@@ -230,7 +245,9 @@ def cli():
230245
Which results in `[default: INFO]` being featured in the help message:
231246

232247
```{click:run}
233-
:emphasize-lines: 20
248+
---
249+
emphasize-lines: 20
250+
---
234251
result = invoke(cli, args=["--help"])
235252
assert (
236253
" \x1b[2m[\x1b[0m\x1b[2mdefault:\n"
@@ -339,7 +356,9 @@ if __name__ == "__main__":
339356
And this simple script gets rendered into:
340357

341358
```{code-block} shell-session
342-
:emphasize-lines: 27-29
359+
---
360+
emphasize-lines: 27-29
361+
---
343362
$ uv run -- python ./wrap.py
344363
Usage: wrap.py [OPTIONS] COMMAND [ARGS]...
345364
@@ -512,7 +531,9 @@ Examples:
512531
Here is the highlighted differences to make them even more obvious:
513532

514533
```{code-block} diff
515-
:emphasize-lines: 2-5,13-14
534+
---
535+
emphasize-lines: 2-5,13-14
536+
---
516537
@@ -1,5 +1,5 @@
517538
-$ uv run -- python ./wrap.py aws_sam --help
518539
-Usage: wrap.py aws_sam [OPTIONS] COMMAND [ARGS]...

0 commit comments

Comments
 (0)