Skip to content

Commit

Permalink
🔧 Update tabs and admonitions with new syntax and new MkDocs features (…
Browse files Browse the repository at this point in the history 
…#906)

* 📝 Update docs tabs to use new pymdownextensions tab blocks

* 📝 Update docs with new admonitions

* 🔧 Update MkDocs config with new Markdown plugins and configs
  • Loading branch information
@tiangolo
tiangolo authored Aug 3, 2024
1 parent a4a3db3 commit 289b230
Show file tree
Hide file tree
Showing 49 changed files with 2,079 additions and 1,174 deletions.
46 changes: 32 additions & 14 deletions docs/alternatives.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -14,24 +14,33 @@ There have been many tools created before that have helped inspire its creation.

It provides a better alternative than reading the *CLI Parameters* as a `list` of `str` and parsing everything by hand.

!!! check "Inspired **Typer** to"
Provide a better development experience than just reading *CLI Parameters* by hand.
/// check | Inspired **Typer** to

Provide a better development experience than just reading *CLI Parameters* by hand.

///

### <a href="https://www.hug.rest/" class="external-link" target="_blank">Hug</a>

Hug is a library to create APIs and CLIs, it uses parameters in functions to declare the required data.

It inspired a lot of the ideas in **FastAPI** and **Typer**.

!!! check "Inspired **Typer** to"
Use function parameters to declare *CLI arguments* and *CLI options* as it simplifies a lot the development experience.
/// check | Inspired **Typer** to

Use function parameters to declare *CLI arguments* and *CLI options* as it simplifies a lot the development experience.

///

### <a href="https://plac.readthedocs.io/en/latest/" class="external-link" target="_blank">Plac</a>

Plac is another library to create CLIs using parameters in functions, similar to Hug.

!!! check "Inspired **Typer** to"
Provide a simple way to use a function as a command line app, without having to create a complete app, with `typer.run(some_function)`.
/// check | Inspired **Typer** to

Provide a simple way to use a function as a command line app, without having to create a complete app, with `typer.run(some_function)`.

///

### <a href="https://pydantic-docs.helpmanual.io/" class="external-link" target="_blank">Pydantic</a>

Expand All @@ -41,8 +50,11 @@ It powers **FastAPI** underneath.

It is not used by **Typer**, but it inspired a lot of the design (through **FastAPI**).

!!! check "Inspired **Typer** to"
Use standard Python type annotations to declare types instead of library-specific types or classes and use them for data validation and documentation.
/// check | Inspired **Typer** to

Use standard Python type annotations to declare types instead of library-specific types or classes and use them for data validation and documentation.

///

### <a href="https://click.palletsprojects.com" class="external-link" target="_blank">Click</a>

Expand All @@ -56,12 +68,15 @@ It uses decorators on top of functions to modify the actual value of those funct

It was built with some great ideas and design using the features available in the language at the time (Python 2.x).

!!! check "**Typer** uses it for"
Everything. 🚀
/// check | **Typer** uses it for

Everything. 🚀

**Typer** mainly adds a layer on top of Click, making the code simpler and easier to use, with autocompletion everywhere, etc, but providing all the powerful features of Click underneath.
**Typer** mainly adds a layer on top of Click, making the code simpler and easier to use, with autocompletion everywhere, etc, but providing all the powerful features of Click underneath.

As someone pointed out: <em><a href="https://twitter.com/fishnets88/status/1210126833745838080" class="external-link" target="_blank">"Nice to see it is built on Click but adds the type stuff. Me gusta!"</a></em>
As someone pointed out: <em><a href="https://twitter.com/fishnets88/status/1210126833745838080" class="external-link" target="_blank">"Nice to see it is built on Click but adds the type stuff. Me gusta!"</a></em>

///

### <a href="https://github.com/click-contrib/click-completion" class="external-link" target="_blank">`click-completion`</a>

Expand All @@ -71,8 +86,11 @@ Previous versions of **Typer** had deep integrations with `click-completion` and

And now **Typer** improved it to have new features, tests, some bug fixes (for issues in plain `click-completion` and Click), and better support for shells, including modern versions of PowerShell (e.g. the default versions that come with Windows 10).

!!! check "Inspired **Typer** to"
Provide auto completion for all the shells.
/// check | Inspired **Typer** to

Provide auto completion for all the shells.

///

### <a href="https://fastapi.tiangolo.com/" class="external-link" target="_blank">FastAPI</a>

Expand Down
119 changes: 68 additions & 51 deletions docs/contributing.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -22,70 +22,83 @@ That will create a directory `./env/` with the Python binaries and then you will

Activate the new environment with:

=== "Linux, macOS"
//// tab | Linux, macOS

<div class="termy">
<div class="termy">

```console
$ source ./env/bin/activate
```

</div>

////

```console
$ source ./env/bin/activate
```
//// tab | Windows PowerShell

</div>
<div class="termy">

=== "Windows PowerShell"
```console
$ .\env\Scripts\Activate.ps1
```

<div class="termy">
</div>

```console
$ .\env\Scripts\Activate.ps1
```
////

</div>
//// tab | Windows Bash

=== "Windows Bash"
Or if you use Bash for Windows (e.g. <a href="https://gitforwindows.org/" class="external-link" target="_blank">Git Bash</a>):

Or if you use Bash for Windows (e.g. <a href="https://gitforwindows.org/" class="external-link" target="_blank">Git Bash</a>):
<div class="termy">

<div class="termy">
```console
$ source ./env/Scripts/activate
```

```console
$ source ./env/Scripts/activate
```
</div>

</div>
////

To check it worked, use:

=== "Linux, macOS, Windows Bash"
//// tab | Linux, macOS, Windows Bash

<div class="termy">
<div class="termy">

```console
$ which pip
```console
$ which pip

some/directory/typer/env/bin/pip
```
some/directory/typer/env/bin/pip
```

</div>
</div>

=== "Windows PowerShell"
////

<div class="termy">
//// tab | Windows PowerShell

```console
$ Get-Command pip
<div class="termy">

some/directory/typer/env/bin/pip
```
```console
$ Get-Command pip

some/directory/typer/env/bin/pip
```

</div>

</div>
////

If it shows the `pip` binary at `env/bin/pip` then it worked. 🎉

!!! tip
Every time you install a new package with `pip` under that environment, activate the environment again.
/// tip

This makes sure that if you use a terminal program installed by that package (like `flit`), you use the one from your local environment and not any other that could be installed globally.
Every time you install a new package with `pip` under that environment, activate the environment again.

This makes sure that if you use a terminal program installed by that package (like `flit`), you use the one from your local environment and not any other that could be installed globally.

///

### Flit

Expand All @@ -107,31 +120,35 @@ Now re-activate the environment to make sure you are using the `flit` you just i

And now use `flit` to install the development dependencies:

=== "Linux, macOS"
//// tab | Linux, macOS

<div class="termy">
<div class="termy">

```console
$ flit install --deps develop --symlink
```console
$ flit install --deps develop --symlink

---> 100%
```
---> 100%
```

</div>
</div>

=== "Windows"
////

If you are on Windows, use `--pth-file` instead of `--symlink`:
//// tab | Windows

<div class="termy">
If you are on Windows, use `--pth-file` instead of `--symlink`:

```console
$ flit install --deps develop --pth-file
<div class="termy">

```console
$ flit install --deps develop --pth-file

---> 100%
```
---> 100%
```

</div>

</div>
////

It will install all the dependencies and your local Typer in your local environment.

Expand Down
32 changes: 19 additions & 13 deletions docs/features.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -48,27 +48,33 @@ The resulting CLI apps created with **Typer** have the nice features of many "pr
* Automatic command and subcommand structure handling (you will see more about subcommands in the Tutorial - User Guide).
* Automatic completion 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 <kbd>TAB</kbd> and get the available options or subcommands. *

!!! note "* Auto completion"
Auto completion works when you create a package (installable with `pip`). Or when using the `typer` command.
/// note | * Auto completion

**Typer** uses `shellingham` to auto-detect the current shell when installing completion. If you don't want to include `shellingham`, install `typer-slim`.
Auto completion works when you create a package (installable with `pip`). Or when using the `typer` command.

**Typer** will automatically create 2 *CLI options*:
**Typer** uses `shellingham` to auto-detect the current shell when installing completion. If you don't want to include `shellingham`, install `typer-slim`.

* `--install-completion`: Install completion for the current shell.
* `--show-completion`: Show completion for the current shell, to copy it or customize the installation.
**Typer** will automatically create 2 *CLI options*:

If you didn't add `shellingham` (if you installed `pip install typer-slim`) those *CLI options* take a value with the name of the shell to install completion for, e.g.:
* `--install-completion`: Install completion for the current shell.
* `--show-completion`: Show completion for the current shell, to copy it or customize the installation.

* `--install-completion bash`.
* `--show-completion powershell`.
If you didn't add `shellingham` (if you installed `pip install typer-slim`) those *CLI options* take a value with the name of the shell to install completion for, e.g.:

Then you can tell the user to install completion after installing your CLI program and the rest will just work.
* `--install-completion bash`.
* `--show-completion powershell`.

!!! tip
**Typer**'s completion is implemented internally, it uses ideas and components from Click and ideas from `click-completion`, but it doesn't use `click-completion` and re-implements some of the relevant parts of Click.
Then you can tell the user to install completion after installing your CLI program and the rest will just work.

Then it extends those ideas with features and bug fixes. For example, **Typer** programs also support modern versions of PowerShell (e.g. in Windows 10) among all the other shells.
///

/// tip

**Typer**'s completion is implemented internally, it uses ideas and components from Click and ideas from `click-completion`, but it doesn't use `click-completion` and re-implements some of the relevant parts of Click.

Then it extends those ideas with features and bug fixes. For example, **Typer** programs also support modern versions of PowerShell (e.g. in Windows 10) among all the other shells.

///

## The power of Click

Expand Down
20 changes: 13 additions & 7 deletions docs/help-typer.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -155,12 +155,15 @@ And if there's any other style or consistency need, I'll ask directly for that,

* Then **comment** saying that you did that, that's how I will know you really checked it.

!!! info
Unfortunately, I can't simply trust PRs that just have several approvals.
/// info

Several times it has happened that there are PRs with 3, 5 or more approvals, probably because the description is appealing, but when I check the PRs, they are actually broken, have a bug, or don't solve the problem they claim to solve. 😅
Unfortunately, I can't simply trust PRs that just have several approvals.

So, it's really important that you actually read and run the code, and let me know in the comments that you did. 🤓
Several times it has happened that there are PRs with 3, 5 or more approvals, probably because the description is appealing, but when I check the PRs, they are actually broken, have a bug, or don't solve the problem they claim to solve. 😅

So, it's really important that you actually read and run the code, and let me know in the comments that you did. 🤓

///

* If the PR can be simplified in a way, you can ask for that, but there's no need to be too picky, there might be a lot of subjective points of view (and I will have my own as well 🙈), so it's better if you can focus on the fundamental things.

Expand Down Expand Up @@ -207,10 +210,13 @@ If you can help me with that, **you are helping me maintain Typer** and making s

Join the 👥 <a href="https://discord.gg/VQjSZaeJmf" class="external-link" target="_blank">FastAPI and Friends Discord chat server</a> 👥 and hang out with others in the community. There's a `#typer` channel.

!!! tip
For questions, ask them in <a href="https://github.com/tiangolo/typer/discussions/new?category=questions" class="external-link" target="_blank">GitHub Discussions</a>, there's a much better chance you will receive help there.
/// tip

For questions, ask them in <a href="https://github.com/tiangolo/typer/discussions/new?category=questions" class="external-link" target="_blank">GitHub Discussions</a>, there's a much better chance you will receive help there.

Use the chat only for other general conversations.

Use the chat only for other general conversations.
///

### Don't use the chat for questions

Expand Down
Loading

0 comments on commit 289b230

Please sign in to comment.