From c941db54278ce6cba4d8eeef6c1b236544aab594 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Sebasti=C3=A1n=20Ram=C3=ADrez?= Date: Sat, 28 Dec 2019 14:12:47 +0100 Subject: [PATCH] :memo: Update docs with references to --install-completion and use subcommand everywhere instead of sub-command for consistency with Click --- README.md | 22 ++++++++++++++-------- docs/features.md | 9 ++++++--- docs/index.md | 22 ++++++++++++++-------- docs/tutorial/index.md | 24 ++++++++++++++++++++---- 4 files changed, 54 insertions(+), 23 deletions(-) diff --git a/README.md b/README.md index 2449017..a15ac00 100644 --- a/README.md +++ b/README.md @@ -34,7 +34,7 @@ The key features are: * **Easy to use**: It's easy to use for the final users. Automatic help commands, and (optional) automatic completion for all shells. * **Short**: Minimize code duplication. Multiple features from each parameter declaration. Fewer bugs. * **Start simple**: The simplest example adds only 2 lines of code to your app: **1 import, 1 function call**. -* **Grow large**: Grow in complexity as much as you want, create arbitrarily complex trees of commands and groups sub-commands, with options and arguments. +* **Grow large**: Grow in complexity as much as you want, create arbitrarily complex trees of commands and groups subcommands, with options and arguments. ## Requirements @@ -94,7 +94,11 @@ $ python main.py --help Usage: main.py [OPTIONS] NAME Options: - --help Show this message and exit. + --install-completion Install completion for the current shell. + --show-completion Show completion for the current shell, to copy it or customize the installation. + --help Show this message and exit. + +// You get a ✨ auto completion ✨ for free, installed with --install-completion // Now pass the NAME argument $ python main.py Camila @@ -112,11 +116,11 @@ This was the simplest example possible. Now let's see one a bit more complex. -### An example with two sub-commands +### An example with two subcommands Modify the file `main.py`. -Create a `typer.Typer()` app, and create two sub-commands with their parameters. +Create a `typer.Typer()` app, and create two subcommands with their parameters. ```Python hl_lines="3 6 11 20" import typer @@ -145,7 +149,7 @@ And that will: * Explicitly create a `typer.Typer` app. * The previous `typer.run` actually creates one implicitly for you. -* Add two sub-commands with `@app.command()`. +* Add two subcommands with `@app.command()`. * Execute the `app()` itself, as if it was a function (instead of `typer.run`). ### Run the upgraded example @@ -159,13 +163,15 @@ $ python main.py --help Usage: main.py [OPTIONS] COMMAND [ARGS]... Options: - --help Show this message and exit. + --install-completion Install completion for the current shell. + --show-completion Show completion for the current shell, to copy it or customize the installation. + --help Show this message and exit. Commands: goodbye hello -// You have 2 sub-commands (the 2 functions): goodbye and hello +// You have 2 subcommands (the 2 functions): goodbye and hello // Now get the --help for hello @@ -231,7 +237,7 @@ or for a `bool` flag: force: bool ``` -And similarly for **files**, **paths**, **enums** (choices), etc. And there are tools to create **groups of sub-commands**, add metadata, extra **validation**, etc. +And similarly for **files**, **paths**, **enums** (choices), etc. And there are tools to create **groups of subcommands**, add metadata, extra **validation**, etc. **You get**: great editor support, including **completion** and **type checks** everywhere. diff --git a/docs/features.md b/docs/features.md index 34f4b1c..46e4ac9 100644 --- a/docs/features.md +++ b/docs/features.md @@ -43,15 +43,18 @@ But by default, it all **"just works"**. The resulting CLI apps created with **Typer** have the nice features of many "pro" command line programs you probably already love. * Automatic help commands and options. -* Automatic command and sub-command structure handling (you will see more about sub-commands in the Tutorial - User Guide). -* Automatic autocompletion for the CLI app in all operating systems, in all the shells (Bash, Zsh, Fish, PowerShell), so that the final user of your app can just hit TAB and get the options of sub-commands. * +* Automatic command and subcommand structure handling (you will see more about subcommands in the Tutorial - User Guide). +* Automatic autocompletion for the CLI app in all operating systems, in all the shells (Bash, Zsh, Fish, PowerShell), so that the final user of your app can just hit TAB and get the available options or subcommands. * !!! note "* Autocompletion" For the autocompletion to work on all shells you also need to add the dependency `click-completion`. Just that. And **Typer** does the rest. - If **Typer** detects `click-completion` installed, it will automatically create a command to install completion for the user's shell. + If **Typer** detects `click-completion` installed, it will automatically create 2 *CLI options*: + + * `--install-completion`: Install completion for the current shell. + * `--show-completion`: Show completion for the current shell, to copy it or customize the installation. Then you can tell the user to run that command and the rest will just work. diff --git a/docs/index.md b/docs/index.md index 2449017..a15ac00 100644 --- a/docs/index.md +++ b/docs/index.md @@ -34,7 +34,7 @@ The key features are: * **Easy to use**: It's easy to use for the final users. Automatic help commands, and (optional) automatic completion for all shells. * **Short**: Minimize code duplication. Multiple features from each parameter declaration. Fewer bugs. * **Start simple**: The simplest example adds only 2 lines of code to your app: **1 import, 1 function call**. -* **Grow large**: Grow in complexity as much as you want, create arbitrarily complex trees of commands and groups sub-commands, with options and arguments. +* **Grow large**: Grow in complexity as much as you want, create arbitrarily complex trees of commands and groups subcommands, with options and arguments. ## Requirements @@ -94,7 +94,11 @@ $ python main.py --help Usage: main.py [OPTIONS] NAME Options: - --help Show this message and exit. + --install-completion Install completion for the current shell. + --show-completion Show completion for the current shell, to copy it or customize the installation. + --help Show this message and exit. + +// You get a ✨ auto completion ✨ for free, installed with --install-completion // Now pass the NAME argument $ python main.py Camila @@ -112,11 +116,11 @@ This was the simplest example possible. Now let's see one a bit more complex. -### An example with two sub-commands +### An example with two subcommands Modify the file `main.py`. -Create a `typer.Typer()` app, and create two sub-commands with their parameters. +Create a `typer.Typer()` app, and create two subcommands with their parameters. ```Python hl_lines="3 6 11 20" import typer @@ -145,7 +149,7 @@ And that will: * Explicitly create a `typer.Typer` app. * The previous `typer.run` actually creates one implicitly for you. -* Add two sub-commands with `@app.command()`. +* Add two subcommands with `@app.command()`. * Execute the `app()` itself, as if it was a function (instead of `typer.run`). ### Run the upgraded example @@ -159,13 +163,15 @@ $ python main.py --help Usage: main.py [OPTIONS] COMMAND [ARGS]... Options: - --help Show this message and exit. + --install-completion Install completion for the current shell. + --show-completion Show completion for the current shell, to copy it or customize the installation. + --help Show this message and exit. Commands: goodbye hello -// You have 2 sub-commands (the 2 functions): goodbye and hello +// You have 2 subcommands (the 2 functions): goodbye and hello // Now get the --help for hello @@ -231,7 +237,7 @@ or for a `bool` flag: force: bool ``` -And similarly for **files**, **paths**, **enums** (choices), etc. And there are tools to create **groups of sub-commands**, add metadata, extra **validation**, etc. +And similarly for **files**, **paths**, **enums** (choices), etc. And there are tools to create **groups of subcommands**, add metadata, extra **validation**, etc. **You get**: great editor support, including **completion** and **type checks** everywhere. diff --git a/docs/tutorial/index.md b/docs/tutorial/index.md index 725300f..984f5e0 100644 --- a/docs/tutorial/index.md +++ b/docs/tutorial/index.md @@ -37,14 +37,24 @@ All the code blocks can be copied and used directly (they are tested Python file To run any of the examples, copy the code to a file `main.py`, and run it: -```bash -python main.py +
+ +```console +$ python main.py + +✨ The magic happens here ✨ ``` +
+ It is **HIGHLY encouraged** that you write or copy the code, edit it and run it locally. Using it in your editor is what really shows you the benefits of Typer, seeing how little code you have to write, all the type checks, autocompletion, etc. +And running the examples is what will really help you understand what is going on. + +You can learn a lot more by running some examples and playing around with them than by reading all the docs here. + --- ## Install Typer @@ -53,8 +63,14 @@ The first step is to install Typer. For the tutorial, you might want to install it with all the optional dependencies and features: -```bash -pip install typer[all] +
+ +```console +$ pip install typer[all] +---> 100% +Successfully installed typer click colorama click-completion ``` +
+ ...that also includes `colorama` and `click-completion`.