Skip to content

Commit

Permalink
Docs cleanup (#185)
Browse files Browse the repository at this point in the history
* update

* try something

* update

* Generate new screengrabs with rich-codex

* updates

* experiment

* update

* Generate new screengrabs with rich-codex

* update

* updates

* Generate new screengrabs with rich-codex

* almost done with docs

* Generate new screengrabs with rich-codex

* update

* delete unused file

---------

Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>
  • Loading branch information
dwreeves and github-actions[bot] committed Apr 22, 2024
1 parent 59c390b commit 7273b45
Show file tree
Hide file tree
Showing 48 changed files with 2,535 additions and 1,352 deletions.
18 changes: 8 additions & 10 deletions .github/workflows/build-docs.yml
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
name: Build images / docs
name: Build docs
on:
workflow_dispatch:
push:
Expand All @@ -15,26 +15,24 @@ jobs:
runs-on: ubuntu-latest
steps:
- name: Check out the repo
uses: actions/checkout@v3
uses: actions/checkout@v4

- name: Set up Python
uses: actions/setup-python@v3
uses: actions/setup-python@v4
with:
python-version: 3.x

- uses: actions/cache@v2
with:
key: ${{ github.ref }}
path: .cache

- name: Install requirements for docs
run: pip install -e ".[docs]"
run: |
pip install -U uv
uv pip install --system --editable ".[docs]"
- name: Generate terminal images with rich-codex
uses: ewels/rich-codex@v1
with:
commit_changes: "true"
clean_img_paths: docs/img/*.svg
clean_img_paths: docs/images/*.svg
skip_git_checks: "true"

- name: Build and deploy docs
run: mkdocs gh-deploy --force
10 changes: 7 additions & 3 deletions .github/workflows/pre-commit.yml
Original file line number Diff line number Diff line change
Expand Up @@ -7,8 +7,12 @@ jobs:
pre-commit:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- uses: actions/setup-python@v3
- uses: actions/checkout@v4
- uses: actions/setup-python@v4
with:
python-version: 3.x
- name: Install dependencies
run: pip install '.[dev]'
run: |
pip install -U uv
uv pip install --system --editable ".[dev]"
- uses: pre-commit/action@v2.0.3
18 changes: 15 additions & 3 deletions .github/workflows/pytest.yml
Original file line number Diff line number Diff line change
Expand Up @@ -5,21 +5,33 @@ jobs:
runs-on: ubuntu-latest
strategy:
matrix:
python: [3.7.x, 3.11.x] # Only test lowest + highest Python versions supported
python: [3.7.x, 3.11.x, 3.12.x]
click: [7.0.*, 7.1.*, 8.0.*, 8.1.*]
rich: [12.*, 13.*]
steps:
- name: Check out the repo
uses: actions/checkout@v3
uses: actions/checkout@v4

- name: Set up Python
uses: actions/setup-python@v4
with:
python-version: ${{ matrix.python }}

- name: Install dependencies
if: matrix.python != '3.7.x'
run: |
pip install '.[dev]'
pip install -U uv
uv pip install --system --editable ".[dev]"
uv pip install --system --upgrade "click==$CLICK_VERSION"
uv pip install --system --upgrade "rich==$RICH_VERSION"
env:
CLICK_VERSION: ${{ matrix.click }}
RICH_VERSION: ${{ matrix.rich }}

- name: Install dependencies (Python 3.7)
if: matrix.python == '3.7.x'
run: |
pip install --editable ".[dev]"
pip install --upgrade "click==$CLICK_VERSION"
pip install --upgrade "rich==$RICH_VERSION"
env:
Expand Down
9 changes: 6 additions & 3 deletions .github/workflows/rich-codex.yml
Original file line number Diff line number Diff line change
Expand Up @@ -11,13 +11,15 @@ jobs:
runs-on: ubuntu-latest
steps:
- name: Check out the repo
uses: actions/checkout@v3
uses: actions/checkout@v4

- name: Set up Python
uses: actions/setup-python@v3
uses: actions/setup-python@v4
with:
python-version: 3.x

- name: Install your custom tools
run: pip install .
run: pip install ".[dev]"

- name: Generate terminal images with rich-codex
uses: ewels/rich-codex@v1
Expand All @@ -26,3 +28,4 @@ jobs:
clean_img_paths: docs/images/*.svg
terminal_width: 80
skip_git_checks: "true"
working_dir: "."
18 changes: 14 additions & 4 deletions .github/workflows/test-examples.yml
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ jobs:
runs-on: ubuntu-latest
strategy:
matrix:
python: [3.7.x, 3.8.x, 3.9.x, 3.10.x, 3.11.x]
python: [3.7.x, 3.11.x, 3.12.x]
click: [7.0.*, 8.0.*, 8.1.*] # Skip click 7.1 since regression coverage is strictly higher in 7.0.
steps:
- name: Check out the repo
Expand All @@ -16,9 +16,19 @@ jobs:
with:
python-version: ${{ matrix.python }}

- name: Install rich-click and click
- name: Install dependencies
if: matrix.python != '3.7.x'
run: |
pip install .
pip install -U uv
uv pip install --system --editable "."
uv pip install --system --upgrade "click==$CLICK_VERSION"
env:
CLICK_VERSION: ${{ matrix.click }}

- name: Install dependencies (Python 3.7)
if: matrix.python == '3.7.x'
run: |
pip install --editable "."
pip install --upgrade "click==$CLICK_VERSION"
env:
CLICK_VERSION: ${{ matrix.click }}
Expand All @@ -28,5 +38,5 @@ jobs:
for f in examples/*py
do
echo -e "\n\n$f"
python $f --help || exit 1;
python "${f}" --help || exit 1;
done
6 changes: 6 additions & 0 deletions .pre-commit-config.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,11 @@ repos:
# hooks:
# - id: prettier

- repo: https://github.com/rhysd/actionlint
rev: v1.6.27
hooks:
- id: actionlint

- repo: https://github.com/tox-dev/pyproject-fmt
rev: 1.7.0
hooks:
Expand All @@ -35,6 +40,7 @@ repos:
hooks:
- id: black
language_version: python3.12
exclude: ^docs/

- repo: local
hooks:
Expand Down
8 changes: 7 additions & 1 deletion .vscode/settings.template.jsonc
Original file line number Diff line number Diff line change
Expand Up @@ -5,5 +5,11 @@
"python.testing.pytestPath": "venv/bin/pytest",
"python.linting.flake8Path": "venv/bin/flake8",
"python.linting.flake8Enabled": true,
"python.testing.pytestEnabled": true
"python.testing.pytestEnabled": true,
"yaml.schemas": {
"https://raw.githubusercontent.com/ewels/rich-codex/main/src/rich_codex/config-schema.yml": [
".rich-codex.yml",
".rich-codex.yaml"
]
}
}
18 changes: 9 additions & 9 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,16 +17,16 @@
- Moved to `text_markup: Literal["markdown", "rich", None]` instead of booleans.
- Fixed issue where error messages would not print to `stderr` by default.
- New configuration options: [[#178](https://github.com/ewels/rich-click/pull/178)]
- `STYLE_OPTIONS_PANEL_BOX`
- `STYLE_COMMANDS_PANEL_BOX`
- `STYLE_ERRORS_PANEL_BOX`
- `STYLE_OPTIONS_PANEL_BOX`
- `STYLE_COMMANDS_PANEL_BOX`
- `STYLE_ERRORS_PANEL_BOX`
- Many 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.
- Better typing for option groups and command groups with `TypedDict` [[#156](https://github.com/ewels/rich-click/pull/156)]
- Added `panel_styles` support to groups. [[#178](https://github.com/ewels/rich-click/pull/178)]
- Allow `table_styles` and `panel_styles` to be defined for the positional arguments group.
- 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.
- Better typing for option groups and command groups with `TypedDict` [[#156](https://github.com/ewels/rich-click/pull/156)]
- Added `panel_styles` support to groups. [[#178](https://github.com/ewels/rich-click/pull/178)]
- Allow `table_styles` and `panel_styles` to be defined for the positional arguments group.

## Version 1.7.4 (2024-03-12)

Expand Down
21 changes: 21 additions & 0 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,27 @@ or better still, dive right in with a pull-request.
3. Install our the package as an editable including all dev dependencies with `pip3 install -e ".[dev]"`
4. Install pre-commit with `pre-commit install`

### One-shot script (OSX)

Requirements:

- `brew install pyenv pyenv-virtualenv uv`
- Initialize `pyenv-virtualenv`: run `pyenv virtualenv-init` and follow instructions.

```
pyenv install --skip-existing 3.7 3.12
pyenv virtualenv 3.7 rich-click-3.7
pyenv virtualenv 3.12 rich-click-3.12
echo '#rich-click-3.7
rich-click-3.12' >.python-version
uv pip install --all-extras -r pyproject.toml --editable .
echo 'rich-click-3.7
#rich-click-3.12' >.python-version
uv pip install --extra dev -r pyproject.toml --editable .
```

Note: 3.7 is the minimum supported Python version for **rich-click**, but docs are rendered in 3.12.

## Pre-commit

Our pre-commit hooks contain the following hooks:
Expand Down
9 changes: 9 additions & 0 deletions docs/code_snippets/introduction_to_click/hello.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
import click

@click.command()
def hello():
"""Prints 'hello, world!' into the terminal."""
print("Hello, world!")

if __name__ == "__main__":
hello()
20 changes: 20 additions & 0 deletions docs/code_snippets/introduction_to_click/hello_rich.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,20 @@
import rich_click as click

@click.group("greetings")
def greetings_cli():
"""CLI for greetings."""

@greetings_cli.command("english")
@click.argument("name")
def english(name):
"""Greet in English"""
print(f"Hello, {name}!")

@greetings_cli.command("french")
@click.argument("name")
def french(name):
"""Greet in French"""
print(f"Bonjour, {name}!")

if __name__ == "__main__":
greetings_cli()
22 changes: 22 additions & 0 deletions docs/code_snippets/introduction_to_click/hello_v2.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,22 @@
import click

@click.command()
@click.argument("name")
@click.option("--times", "-t",
default=1,
type=click.INT,
show_default=True,
help="Number of times to print the greeting.")
@click.option("--say-goodbye",
is_flag=True,
default=False,
help="After saying hello, say goodbye.")
def hello(name, times, say_goodbye):
"""Prints 'hello, [name]!' into the terminal N times."""
for t in range(times):
print(f"Hello, {name}!")
if say_goodbye:
print("Goodbye!")

if __name__ == "__main__":
hello()
20 changes: 20 additions & 0 deletions docs/code_snippets/introduction_to_click/hello_v3.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,20 @@
import click

@click.group("greetings")
def greetings_cli():
"""CLI for greetings."""

@greetings_cli.command("english")
@click.argument("name")
def english(name):
"""Greet in English"""
print(f"Hello, {name}!")

@greetings_cli.command("french")
@click.argument("name")
def french(name):
"""Greet in French"""
print(f"Bonjour, {name}!")

if __name__ == "__main__":
greetings_cli()
68 changes: 68 additions & 0 deletions docs/code_snippets/rich_click_cli/app.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,68 @@
# This is a fleshed-out application built with Click.
# (Except for the fact that it doesn't do anything!)
#
# Run the command `rich-click app:main --help` to render it with rich-click!
import logging

import click
from rich.logging import RichHandler

logger = logging.getLogger(__name__)
logger.addHandler(RichHandler())
logger.setLevel(logging.INFO)

@click.group("my-app")
@click.option("--environment", "-e",
type=click.Choice(["production", "staging", "integration"]),
default="production",
show_default=True,
help="Environment to run in.")
@click.version_option(version="1.0.1", prog_name="my-app")
def main(environment):
"""CLI for my-app"""
logger.debug("Running in environment=%s", environment)


@main.command("deploy")
@click.argument("version")
@click.pass_context
def deploy(ctx, version):
"""Deploy my-app"""
logger.info("Deploying version=%s in environment=%s", version, ctx.parent.params["environment"])

@main.group("user")
def user_cli():
"""Manage users to my-app"""

@user_cli.command("create")
@click.option("--email", "-e",
required=True,
help="User's email")
@click.password_option("--password", "-p",
required=True,
prompt=True,
help="User's password")
@click.option("--admin",
is_flag=True,
default=False,
help="If flag is passed, give admin permissions")
@click.pass_context
def create(ctx, email, password, admin):
"""Create my-app users"""
if len(password) < 6:
logger.error("Password must be ≥ 6 characters")
ctx.exit(1)
logger.info("Creating user with email=%s admin=%s", email, admin)


@user_cli.command("delete")
@click.argument("user_id",
type=click.INT)
def delete(user_id):
"""Delete my-app users"""
click.confirm(click.style(f"Are you sure you want to delete user={user_id!r}?", fg="red"), abort=True)
logger.info("Deleting user with user_id=%i", user_id)


if __name__ == "__main__":
main()
Loading

0 comments on commit 7273b45

Please sign in to comment.