Skip to content

Commit

Permalink
Some final revisions (#177)
Browse files Browse the repository at this point in the history
* docs refactor - use template instead of md file

* update

* py37

* bump version
  • Loading branch information
dwreeves authored Apr 13, 2024
1 parent 9bb21ef commit 3103ecd
Show file tree
Hide file tree
Showing 15 changed files with 819 additions and 861 deletions.
6 changes: 5 additions & 1 deletion CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,9 +14,13 @@
- Fix bug with regex highlighter for options and switches.
- `RichHelpConfiguration()` is now asserted to be JSON serializable, as an option for porting configurations. That said, serialization is not a fully supported feature of the high-level API, so serialize the config at your own risk.
- Related: `highlighter` is now deprecated in `RichHelpConfiguration`; please use `highlighter_patterns` instead.
- Moved exclusively to `pyproject.toml` and removed `setup.py` / `setup.cfg`; thank you [@Stealthii](github.com/Stealthii)!
- Moved exclusively to `pyproject.toml` and removed `setup.py` / `setup.cfg`; thank you [@Stealthii](https://github.com/Stealthii)!
- Moved to `text_markup: Literal["markdown", "rich", None]` instead of booleans.
- Fixed issue where error messages would not print to `stderr` by default.
- Some quality of life improvements for command and option groups:
- Support both `command_path` and `command.name`
- Added wildcard (`*`) option for command groups and option groups, with thanks to [@ITProKyle](https://github.com/ITProKyle)!
- Resolve duplicates.

## Version 1.7.4 (2024-03-12)

Expand Down
16 changes: 13 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -32,7 +32,8 @@ Click, formatted with Rich, with minimal customisation required.
## Features

- 🌈 Rich command-line formatting of click help and error messages
- 💫 Nice styles be default, usage is simply `import rich_click as click`
- 😌 Same API as Click: usage is simply `import rich_click as click`
- 💫 Nice styles by default
- 💻 CLI tool to run on _other people's_ tools (prefix the command with `rich-click`)
- 📦 Export help text as HTML or SVG
- 🎁 Group commands and options into named panels
Expand Down Expand Up @@ -75,7 +76,7 @@ _Screenshot from [`examples/11_hello.py`](examples/11_hello.py)_

### More complex example

![examples/03_groups_sorting.py](docs/images/command_groups.svg)
![`python examples/03_groups_sorting.py`](docs/images/command_groups.svg)

_Screenshot from [`examples/03_groups_sorting.py`](examples/03_groups_sorting.py)_

Expand All @@ -99,9 +100,18 @@ That's it! ✨ Then continue to use Click as you would normally.
### Declarative

If you prefer, you can `RichGroup` or `RichCommand` with the `cls` argument in your click usage instead.
If you prefer, you can use `RichGroup` or `RichCommand` with the `cls` argument in your click usage instead.
This means that you can continue to use the unmodified `click` package in parallel.

```python
import click
from rich_click import RichCommand

@click.command(cls=RichCommand)
def main():
"""My amazing tool does all the things."""
```

> See [`examples/02_declarative.py`](examples/02_declarative.py) for an example.
### `rich-click` CLI tool
Expand Down
139 changes: 139 additions & 0 deletions docs/css/editor.css
Original file line number Diff line number Diff line change
@@ -0,0 +1,139 @@
#terminal-header {
text-shadow: -4px 4px rgba(128, 128, 128, 0.1);
overflow: hidden;
white-space: nowrap;
margin: 0 auto;
padding: 10px;
display: inline-block;
}

[data-termynal] {
width: 100%;
padding: 75px 25px 25px;
}

.container {
display: flex;
height: 100%;
}

.container .left-column {
flex: 3 0 auto;
align-content: center;
}

.container .right-column {
flex: 20 7 auto;
padding: 25px 15px;
align-content: center;
display: inline-block;
}

@media (max-width: 74em) {
.container {
flex-direction: column;
align-items: center;
width: 100%;
}

.container .left-column, .container .right-column {
flex: 0 0 auto;
padding: 0;
width: 100%;
display: block;
}

#option-table {
margin: 0;
padding: 0;
width: 100%;
table-layout: fixed;
}

@media (max-width: 600px) {
#option-table th:first-child, td:first-child {
max-width: 15em;
overflow: hidden;
}
}

}

.rc-element.c-black {
color: #000000;
}
.rc-element.c-blue {
color: #0088CC;
}
.rc-element.c-green {
color: #338022;
}
.rc-element.c-yellow {
color: #AA8800;
}
.rc-element.c-cyan {
color: #009090;
}
.rc-element.c-white {
color: #c0c0c0;
}
.rc-element.c-magenta {
color: #9966AA;
}
.rc-element.c-red {
color: #EE5555;
}
.rc-element.s-italic {
font-style: italic;
}
.rc-element.s-bold {
font-weight: bold;
}
.rc-element.s-dim {
opacity: 50%;
}
.color-option[data-color="black"] {
background-color: #000000;
}
.color-option[data-color="blue"] {
background-color: #0088CC;
}
.color-option[data-color="green"] {
background-color: #338022;
}
.color-option[data-color="yellow"] {
background-color: #AA8800;
}
.color-option[data-color="cyan"] {
background-color: #009090;
}
.color-option[data-color="white"] {
background-color: #c0c0c0;
}
.color-option[data-color="magenta"] {
background-color: #9966AA;
}
.color-option[data-color="red"] {
background-color: #EE5555;
}
.color-grid {
display: grid;
grid-template-columns: repeat(4, 1.1em);
grid-gap: 0.2em;
}
.color-option {
width: 1.1em;
height: 1.1em;
cursor: pointer;
opacity: 0.2;
transition: opacity 0.2s ease;
}
.color-option:hover {
opacity: 0.8;
}
.color-option.selected-color {
opacity: 1;
}
.rc-button.button-selected code {
background-color: rgba(127, 127, 127, 0.4);
}
48 changes: 45 additions & 3 deletions docs/css/extra.css
Original file line number Diff line number Diff line change
Expand Up @@ -43,9 +43,51 @@ a.internal-link::after {
url("../fonts/pixelmix.ttf") format("truetype")
}

.md-header__topic, h1, h1 code, .md-header__header {
.md-header__topic, .md-header__topic code,
h1, h1 code, h2, h2 code, h3, h3 code,
h4, h4 code, h5, h5 code,
.md-header__header, .md-header__header code {
font-family: "pixelmix";
font-size: 24px;
font-weight: normal;
}

.md-header__topic, .md-header__topic code, h1, h1 code, .md-header__header {
text-shadow: -4px 4px rgba(128, 128, 128, 0.1);
}

h2, h2 code, h3, h3 code {
text-shadow: -3px 3px rgba(128, 128, 128, 0.1);
}

h4, h4 code, h5, h5 code {
text-shadow: -2px 2px rgba(128, 128, 128, 0.1);
}

.md-content ul {
list-style: none;
}

.md-content ul > li {
position: relative;
padding-left: 20px;
}

.md-content ul > li::before {
content: '';
display: inline-block;
width: 8px;
height: 8px;
background-color: var(--md-typeset-color);
opacity: 90%;
position: absolute;
left: 0;
top: 0;
margin-top: 0.8em;
transform: translateY(-50%);
transition: background-color 0.2s ease;
}

.md-content ul > li:hover::before {
background-color: var(--md-accent-fg-color);
fill-opacity: 100%;
opacity: 100%;
}
2 changes: 1 addition & 1 deletion docs/documentation/formatting_and_styles.md
Original file line number Diff line number Diff line change
Expand Up @@ -72,7 +72,7 @@ If you prefer, you can use Markdown text.
The default click behaviour is to only show positional arguments in the top usage string,
and not in the list below with the options.

If you prefer, you can tell rich-click to show arguments with `SHOW_ARGUMENTS`.
If you prefer, you can tell **rich-click** to show arguments with `SHOW_ARGUMENTS`.
By default, they will get their own panel, but you can tell rich-click to bundle them together with `GROUP_ARGUMENTS_OPTIONS`:

=== "`RichHelpConfiguration()`"
Expand Down
66 changes: 32 additions & 34 deletions docs/documentation/groups_and_sorting.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,39 +6,7 @@ It accepts a list of options / commands which means you can also choose a custom
- For options / flags, set `click.rich_click.OPTION_GROUPS`
- For subcommands / Click groups, set `click.rich_click.COMMAND_GROUPS`

<div class="termy termy-static" static="true" style="width: 100%">

```console
$ python examples/03_groups_sorting.py --help

<span style="color: #808000; text-decoration-color: #808000">Usage:</span> <span style="font-weight: bold">03_groups_sorting.py</span> [<span style="color: #008080; text-decoration-color: #008080; font-weight: bold">OPTIONS</span>] <span style="color: #008080; text-decoration-color: #008080; font-weight: bold">COMMAND</span> [<span style="color: #008080; text-decoration-color: #008080; font-weight: bold">ARGS</span>]...
My amazing tool does all the things.
<span style="color: #7f7f7f; text-decoration-color: #7f7f7f">This is a minimal example based on documentation from the &#x27;click&#x27; </span>
<span style="color: #7f7f7f; text-decoration-color: #7f7f7f">package.</span>
<span style="color: #7f7f7f; text-decoration-color: #7f7f7f">You can try using </span><span style="color: #7fbfbf; text-decoration-color: #7fbfbf; font-weight: bold">--help</span><span style="color: #7f7f7f; text-decoration-color: #7f7f7f"> at the top level and also for specific </span>
<span style="color: #7f7f7f; text-decoration-color: #7f7f7f">subcommands.</span>
<span style="color: #7f7f7f; text-decoration-color: #7f7f7f">╭─ Options ────────────────────────────────────────────────────────────╮</span>
<span style="color: #7f7f7f; text-decoration-color: #7f7f7f">│</span> <span style="color: #800000; text-decoration-color: #800000">*</span> <span style="color: #008080; text-decoration-color: #008080; font-weight: bold">--type</span> <span style="color: #808000; text-decoration-color: #808000; font-weight: bold">TEXT</span> Type of file to sync <span style="color: #7f7f7f; text-decoration-color: #7f7f7f">│</span>
<span style="color: #7f7f7f; text-decoration-color: #7f7f7f">│</span> <span style="color: #7f7f7f; text-decoration-color: #7f7f7f">[default: files] </span> <span style="color: #7f7f7f; text-decoration-color: #7f7f7f">│</span>
<span style="color: #7f7f7f; text-decoration-color: #7f7f7f">│</span> <span style="color: #bf7f7f; text-decoration-color: #bf7f7f">[required] </span> <span style="color: #7f7f7f; text-decoration-color: #7f7f7f">│</span>
<span style="color: #7f7f7f; text-decoration-color: #7f7f7f">│</span> <span style="color: #008080; text-decoration-color: #008080; font-weight: bold">--debug</span>/<span style="color: #008080; text-decoration-color: #008080; font-weight: bold">--no-debug</span> <span style="color: #008000; text-decoration-color: #008000; font-weight: bold">-d</span>/<span style="color: #008000; text-decoration-color: #008000; font-weight: bold">-n</span> <span style="color: #808000; text-decoration-color: #808000; font-weight: bold"> </span> Show the debug log messages <span style="color: #7f7f7f; text-decoration-color: #7f7f7f">│</span>
<span style="color: #7f7f7f; text-decoration-color: #7f7f7f">│</span> <span style="color: #7f7f7f; text-decoration-color: #7f7f7f">[default: no-debug] </span> <span style="color: #7f7f7f; text-decoration-color: #7f7f7f">│</span>
<span style="color: #7f7f7f; text-decoration-color: #7f7f7f">│</span> <span style="color: #008080; text-decoration-color: #008080; font-weight: bold">--version</span> <span style="color: #808000; text-decoration-color: #808000; font-weight: bold"> </span> Show the version and exit. <span style="color: #7f7f7f; text-decoration-color: #7f7f7f">│</span>
<span style="color: #7f7f7f; text-decoration-color: #7f7f7f">│</span> <span style="color: #008080; text-decoration-color: #008080; font-weight: bold">--help</span> <span style="color: #008000; text-decoration-color: #008000; font-weight: bold">-h</span> <span style="color: #808000; text-decoration-color: #808000; font-weight: bold"> </span> Show this message and exit. <span style="color: #7f7f7f; text-decoration-color: #7f7f7f">│</span>
<span style="color: #7f7f7f; text-decoration-color: #7f7f7f">╰──────────────────────────────────────────────────────────────────────╯</span>
<span style="color: #7f7f7f; text-decoration-color: #7f7f7f">╭─ Main usage ─────────────────────────────────────────────────────────╮</span>
<span style="color: #7f7f7f; text-decoration-color: #7f7f7f">│</span> <span style="color: #008080; text-decoration-color: #008080; font-weight: bold">sync </span> Synchronise all your files between two places. <span style="color: #7f7f7f; text-decoration-color: #7f7f7f">│</span>
<span style="color: #7f7f7f; text-decoration-color: #7f7f7f">│</span> <span style="color: #008080; text-decoration-color: #008080; font-weight: bold">download </span> Pretend to download some files from somewhere. <span style="color: #7f7f7f; text-decoration-color: #7f7f7f">│</span>
<span style="color: #7f7f7f; text-decoration-color: #7f7f7f">╰──────────────────────────────────────────────────────────────────────╯</span>
<span style="color: #7f7f7f; text-decoration-color: #7f7f7f">╭─ Configuration ──────────────────────────────────────────────────────╮</span>
<span style="color: #7f7f7f; text-decoration-color: #7f7f7f">│</span> <span style="color: #008080; text-decoration-color: #008080; font-weight: bold">config </span> Set up the configuration. <span style="color: #7f7f7f; text-decoration-color: #7f7f7f">│</span>
<span style="color: #7f7f7f; text-decoration-color: #7f7f7f">│</span> <span style="color: #008080; text-decoration-color: #008080; font-weight: bold">auth </span> Authenticate the app. <span style="color: #7f7f7f; text-decoration-color: #7f7f7f">│</span>
<span style="color: #7f7f7f; text-decoration-color: #7f7f7f">╰──────────────────────────────────────────────────────────────────────╯</span>
```

</div>
![](../images/command_groups.svg)

When grouping subcommands into more than one group (in above example: 'Main usage' and 'Configuration') you may find that the automatically calculated widths of different groups do not line up, due to varying option name lengths.

Expand Down Expand Up @@ -107,10 +75,40 @@ click.rich_click.COMMAND_GROUPS = {
"commands": ["get", "fetch", "download"],
},
],
"mytool auth":[{"commands": ["login", "logout"]}],
"mytool auth": [{"commands": ["login", "logout"]}],
}
```

## Wildcard options

Instead of defining the group based on the command path, you can use wildcards instead:

```python
click.rich_click.COMMAND_GROUPS = {
"*": [
{
"name": "Commands for uploading",
"commands": ["sync", "upload"],
}
]
}

click.rich_click.OPTION_GROUPS = {
"*": [
{
"name": "Simple options",
"options": ["--name", "--description", "--version", "--help"],
},
]
}
```

This will apply the groups to every subcommand of the command group.
If a command or option specified in the wildcard does not exist, then it is ignored.

If an option is specified for both a wildcard and explicitly named command, then the wildcard is ignored;
explicit naming always takes precedence.

## Table styling

Typically you would style the option / command tables using the global config options.
Expand Down
Loading

0 comments on commit 3103ecd

Please sign in to comment.