deploy: c2f6e48

.buildinfo

@@ -0,0 +1,4 @@
+# Sphinx build info version 1
+# This file records the configuration used when building these files. When it is not found, a full rebuild will be done.
+config: 3d483dc14313dfd58bb9d7a7ff0ec365
+tags: 645f666f9bcd5a90fca523b33c5a78b7

_sources/changelog.md.txt

@@ -0,0 +1,2 @@
+```{include} ../changelog.md
+```

_sources/click_extra.rst.txt

@@ -0,0 +1,130 @@
+click\_extra package
+====================
+
+.. automodule:: click_extra
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Submodules
+----------
+
+click\_extra.colorize module
+----------------------------
+
+.. automodule:: click_extra.colorize
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+click\_extra.commands module
+----------------------------
+
+.. automodule:: click_extra.commands
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+click\_extra.config module
+--------------------------
+
+.. automodule:: click_extra.config
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+click\_extra.decorators module
+------------------------------
+
+.. automodule:: click_extra.decorators
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+click\_extra.docs\_update module
+--------------------------------
+
+.. automodule:: click_extra.docs_update
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+click\_extra.logging module
+---------------------------
+
+.. automodule:: click_extra.logging
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+click\_extra.parameters module
+------------------------------
+
+.. automodule:: click_extra.parameters
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+click\_extra.pygments module
+----------------------------
+
+.. automodule:: click_extra.pygments
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+click\_extra.pytest module
+--------------------------
+
+.. automodule:: click_extra.pytest
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+click\_extra.sphinx module
+--------------------------
+
+.. automodule:: click_extra.sphinx
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+click\_extra.tabulate module
+----------------------------
+
+.. automodule:: click_extra.tabulate
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+click\_extra.telemetry module
+-----------------------------
+
+.. automodule:: click_extra.telemetry
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+click\_extra.testing module
+---------------------------
+
+.. automodule:: click_extra.testing
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+click\_extra.timer module
+-------------------------
+
+.. automodule:: click_extra.timer
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+click\_extra.version module
+---------------------------
+
+.. automodule:: click_extra.version
+   :members:
+   :undoc-members:
+   :show-inheritance:

_sources/code-of-conduct.md.txt

@@ -0,0 +1,7 @@
+# Code of conduct
+
+```{include} ../.github/code-of-conduct.md
+---
+start-line: 2
+---
+```

_sources/colorize.md.txt

@@ -0,0 +1,148 @@
+# Colored help
+
+Extend
+[Cloup's own help formatter and theme](https://cloup.readthedocs.io/en/stable/pages/formatting.html#help-formatting-and-themes)
+to add colorization of:
+
+- Options
+
+- Choices
+
+- Metavars
+
+- Cli name
+
+- Sub-commands
+
+- Command aliases
+
+- Long and short options
+
+- Choices
+
+- Metavars
+
+- Environment variables
+
+- Defaults
+
+```{todo}
+Write examples and tutorial.
+```
+
+## Why not use `rich-click`?
+
+[`rich-click`](https://github.com/ewels/rich-click) is a good project that aims to integrate [Rich](https://github.com/Textualize/rich) with Click. Like Click Extra, it provides a ready-to-use help formatter for Click.
+
+But contrary to Click Extra, the [help screen is rendered within a table](https://github.com/ewels/rich-click#styling), which takes the whole width of the terminal. This is not ideal if you try to print the output of a command somewhere else.
+
+The typical use-case is users reporting issues on GitHub, and pasting the output of a command in the issue description. If the output is too wide, it will be akwardly wrapped, or [adds a horizontal scrollbar](https://github.com/callowayproject/bump-my-version/pull/23#issuecomment-1602007874) to the page.
+
+Without a table imposing a maximal width, the help screens from Click Extra will be rendered with the minimal width of the text, and will be more readable.
+
+```{hint}
+This is just a matter of preference, as nothing prevents you to use both `rich-click` and Click Extra in the same project, and get the best from both.
+```
+
+## `color_option`
+
+```{todo}
+Write examples and tutorial.
+```
+
+## `help_option`
+
+```{todo}
+Write examples and tutorial.
+```
+
+## Colors and styles
+
+Here is a little CLI to demonstrate the rendering of colors and styles, based on [`cloup.styling.Style`](https://cloup.readthedocs.io/en/stable/autoapi/cloup/styling/index.html#cloup.styling.Style):
+
+```{eval-rst}
+.. click:example::
+   from click import command
+   from click_extra import Color, style, Choice, option
+   from click_extra.tabulate import render_table
+
+   all_styles = [
+      "bold",
+      "dim",
+      "underline",
+      "overline",
+      "italic",
+      "blink",
+      "reverse",
+      "strikethrough",
+   ]
+
+   all_colors = sorted(Color._dict.values())
+
+   @command
+   @option("--matrix", type=Choice(["colors", "styles"]))
+   def render_matrix(matrix):
+      table = []
+
+      if matrix == "colors":
+         table_headers = ["Foreground ↴ \ Background →"] + all_colors
+         for fg_color in all_colors:
+            line = [
+               style(fg_color, fg=fg_color)
+            ]
+            for bg_color in all_colors:
+               line.append(
+                  style(fg_color, fg=fg_color, bg=bg_color)
+               )
+            table.append(line)
+
+      elif matrix == "styles":
+         table_headers = ["Color ↴ \ Style →"] + all_styles
+         for color_name in all_colors:
+            line = [
+               style(color_name, fg=color_name)
+            ]
+            for prop in all_styles:
+               line.append(
+                  style(color_name, fg=color_name, **{prop: True})
+               )
+            table.append(line)
+
+      render_table(table, headers=table_headers)
+
+.. click:run::
+   result = invoke(render_matrix, ["--matrix=colors"])
+   assert "\x1b[95mbright_magenta\x1b[0m" in result.stdout
+   assert "\x1b[95m\x1b[101mbright_magenta\x1b[0m" in result.stdout
+
+.. click:run::
+   result = invoke(render_matrix, ["--matrix=styles"])
+   assert "\x1b[97mbright_white\x1b[0m" in result.stdout
+   assert "\x1b[97m\x1b[1mbright_white\x1b[0m" in result.stdout
+   assert "\x1b[97m\x1b[2mbright_white\x1b[0m" in result.stdout
+   assert "\x1b[97m\x1b[4mbright_white\x1b[0m" in result.stdout
+```
+
+```{caution}
+The current rendering of colors and styles in this HTML documentation is not complete, and does not reflect the real output in a terminal.
+
+That is because [`pygments-ansi-color`](https://github.com/chriskuehl/pygments-ansi-color), the component we rely on to render ANSI code in Sphinx via Pygments, [only supports a subset of the ANSI codes](https://github.com/chriskuehl/pygments-ansi-color/issues/31) we use.
+```
+
+```{tip}
+The code above is presented as a CLI, so you can copy and run it yourself in your environment, and see the output in your terminal. That way you can evaluate the real effect of these styles and colors for your end users.
+```
+
+## `click_extra.colorize` API
+
+```{eval-rst}
+.. autoclasstree:: click_extra.colorize
+   :strict:
+```
+
+```{eval-rst}
+.. automodule:: click_extra.colorize
+   :members:
+   :undoc-members:
+   :show-inheritance:
+```