Skip to content

📝 Update markdown includes to use the new simpler format #1054

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 4 commits into from
Nov 18, 2024
Merged

📝 Update markdown includes to use the new simpler format #1054

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
83b95ce
➕ Add Add markdown-include-variants to docs dependencies
tiangolo Nov 18, 2024
1f31870
🔧 Udpate MkDocs config with the new markdown-includes
tiangolo Nov 18, 2024
e9ceec8
📝 Update markdown includes with new format
tiangolo Nov 18, 2024
06f3324
Merge branch 'master' into markdown-includes
tiangolo Nov 18, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 1 addition & 3 deletions docs/tutorial/app-dir.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,9 +2,7 @@

You can get the application directory where you can, for example, save configuration files with `typer.get_app_dir()`:

```Python hl_lines="9"
{!../docs_src/app_dir/tutorial001.py!}
```
{* docs_src/app_dir/tutorial001.py hl[9] *}

It will give you a directory for storing configurations appropriate for your CLI program for the current user in each operating system.

Expand Down
44 changes: 2 additions & 42 deletions docs/tutorial/arguments/default.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,27 +8,7 @@ That way the *CLI argument* will be optional *and also* have a default value.

We can also use `typer.Argument()` to make a *CLI argument* have a default value other than `None`:

//// tab | Python 3.7+

```Python hl_lines="5"
{!> ../docs_src/arguments/default/tutorial001_an.py!}
```

////

//// tab | Python 3.7+ non-Annotated

/// tip

Prefer to use the `Annotated` version if possible.

///

```Python hl_lines="4"
{!> ../docs_src/arguments/default/tutorial001.py!}
```

////
{* docs_src/arguments/default/tutorial001_an.py hl[5] *}

/// tip

Expand Down Expand Up @@ -72,27 +52,7 @@ Hello Camila

And we can even make the default value be dynamically generated by passing a function as the `default_factory` argument:

//// tab | Python 3.7+

```Python hl_lines="7-8 11"
{!> ../docs_src/arguments/default/tutorial002_an.py!}
```

////

//// tab | Python 3.7+ non-Annotated

/// tip

Prefer to use the `Annotated` version if possible.

///

```Python hl_lines="6-7 10"
{!> ../docs_src/arguments/default/tutorial002.py!}
```

////
{* docs_src/arguments/default/tutorial002_an.py hl[7:8,11] *}

In this case, we created the function `get_name` that will just return a random `str` each time.

Expand Down
66 changes: 3 additions & 63 deletions docs/tutorial/arguments/envvar.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,27 +10,7 @@ You can learn more about environment variables in the [Environment Variables](..

To do that, use the `envvar` parameter for `typer.Argument()`:

//// tab | Python 3.7+

```Python hl_lines="5"
{!> ../docs_src/arguments/envvar/tutorial001_an.py!}
```

////

//// tab | Python 3.7+ non-Annotated

/// tip

Prefer to use the `Annotated` version if possible.

///

```Python hl_lines="4"
{!> ../docs_src/arguments/envvar/tutorial001.py!}
```

////
{* docs_src/arguments/envvar/tutorial001_an.py hl[5] *}

In this case, the *CLI argument* `name` will have a default value of `"World"`, but will also read any value passed to the environment variable `AWESOME_NAME` if no value is provided in the command line:

Expand Down Expand Up @@ -75,27 +55,7 @@ Hello Mr. Czernobog

You are not restricted to a single environment variable, you can declare a list of environment variables that could be used to get a value if it was not passed in the command line:

//// tab | Python 3.7+

```Python hl_lines="6"
{!> ../docs_src/arguments/envvar/tutorial002_an.py!}
```

////

//// tab | Python 3.7+ non-Annotated

/// tip

Prefer to use the `Annotated` version if possible.

///

```Python hl_lines="4"
{!> ../docs_src/arguments/envvar/tutorial002.py!}
```

////
{* docs_src/arguments/envvar/tutorial002_an.py hl[6] *}

Check it:

Expand Down Expand Up @@ -130,27 +90,7 @@ Hello Mr. Anubis

By default, environment variables used will be shown in the help text, but you can disable them with `show_envvar=False`:

//// tab | Python 3.7+

```Python hl_lines="7"
{!> ../docs_src/arguments/envvar/tutorial003_an.py!}
```

////

//// tab | Python 3.7+ non-Annotated

/// tip

Prefer to use the `Annotated` version if possible.

///

```Python hl_lines="4"
{!> ../docs_src/arguments/envvar/tutorial003.py!}
```

////
{* docs_src/arguments/envvar/tutorial003_an.py hl[7] *}

Check it:

Expand Down
180 changes: 9 additions & 171 deletions docs/tutorial/arguments/help.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,37 +4,15 @@ In the *First Steps* section you saw how to add help for a CLI app/command by ad

Here's how that last example looked like:

```Python
{!../docs_src/first_steps/tutorial006.py!}
```
{* docs_src/first_steps/tutorial006.py *}

Now that you also know how to use `typer.Argument()`, let's use it to add documentation specific for a *CLI argument*.

## Add a `help` text for a *CLI argument*

You can use the `help` parameter to add a help text for a *CLI argument*:

//// tab | Python 3.7+

```Python hl_lines="5"
{!> ../docs_src/arguments/help/tutorial001_an.py!}
```

////

//// tab | Python 3.7+ non-Annotated

/// tip

Prefer to use the `Annotated` version if possible.

///

```Python hl_lines="4"
{!> ../docs_src/arguments/help/tutorial001.py!}
```

////
{* docs_src/arguments/help/tutorial001_an.py hl[5] *}

And it will be used in the automatic `--help` option:

Expand All @@ -59,27 +37,7 @@ Options:

And of course, you can also combine that `help` with the <abbr title="a multi-line string as the first expression inside a function (not assigned to any variable) used for documentation">docstring</abbr>:

//// tab | Python 3.7+

```Python hl_lines="5-8"
{!> ../docs_src/arguments/help/tutorial002_an.py!}
```

////

//// tab | Python 3.7+ non-Annotated

/// tip

Prefer to use the `Annotated` version if possible.

///

```Python hl_lines="4-7"
{!> ../docs_src/arguments/help/tutorial002.py!}
```

////
{* docs_src/arguments/help/tutorial002_an.py hl[5:8] *}

And the `--help` option will combine all the information:

Expand All @@ -106,27 +64,7 @@ Options:

If you have a *CLI argument* with a default value, like `"World"`:

//// tab | Python 3.7+

```Python hl_lines="5"
{!> ../docs_src/arguments/help/tutorial003_an.py!}
```

////

//// tab | Python 3.7+ non-Annotated

/// tip

Prefer to use the `Annotated` version if possible.

///

```Python hl_lines="4"
{!> ../docs_src/arguments/help/tutorial003.py!}
```

////
{* docs_src/arguments/help/tutorial003_an.py hl[5] *}

It will show that default value in the help text:

Expand All @@ -151,27 +89,7 @@ Options:

But you can disable that if you want to, with `show_default=False`:

//// tab | Python 3.7+

```Python hl_lines="7"
{!> ../docs_src/arguments/help/tutorial004_an.py!}
```

////

//// tab | Python 3.7+ non-Annotated

/// tip

Prefer to use the `Annotated` version if possible.

///

```Python hl_lines="4"
{!> ../docs_src/arguments/help/tutorial004.py!}
```

////
{* docs_src/arguments/help/tutorial004_an.py hl[7] *}

And then it won't show the default value:

Expand Down Expand Up @@ -206,27 +124,7 @@ In **Typer** these default values are shown by default. 👀

You can use the same `show_default` to pass a custom string (instead of a `bool`) to customize the default value to be shown in the help text:

//// tab | Python 3.7+

```Python hl_lines="9"
{!> ../docs_src/arguments/help/tutorial005_an.py!}
```

////

//// tab | Python 3.7+ non-Annotated

/// tip

Prefer to use the `Annotated` version if possible.

///

```Python hl_lines="6"
{!> ../docs_src/arguments/help/tutorial005.py!}
```

////
{* docs_src/arguments/help/tutorial005_an.py hl[9] *}

And it will be used in the help text:

Expand Down Expand Up @@ -271,27 +169,7 @@ But you can customize it with the `metavar` parameter for `typer.Argument()`.

For example, let's say you don't want to have the default of `NAME`, you want to have `username`, in lowercase, and you really want ✨ emojis ✨ everywhere:

//// tab | Python 3.7+

```Python hl_lines="5"
{!> ../docs_src/arguments/help/tutorial006_an.py!}
```

////

//// tab | Python 3.7+ non-Annotated

/// tip

Prefer to use the `Annotated` version if possible.

///

```Python hl_lines="4"
{!> ../docs_src/arguments/help/tutorial006.py!}
```

////
{* docs_src/arguments/help/tutorial006_an.py hl[5] *}

Now the generated help text will have `✨username✨` instead of `NAME`:

Expand All @@ -317,27 +195,7 @@ You might want to show the help information for *CLI arguments* in different pan

If you have installed Rich as described in the docs for [Printing and Colors](../printing.md){.internal-link target=_blank}, you can set the `rich_help_panel` parameter to the name of the panel where you want this *CLI argument* to be shown:

//// tab | Python 3.7+

```Python hl_lines="8 12"
{!> ../docs_src/arguments/help/tutorial007_an.py!}
```

////

//// tab | Python 3.7+ non-Annotated

/// tip

Prefer to use the `Annotated` version if possible.

///

```Python hl_lines="7 10"
{!> ../docs_src/arguments/help/tutorial007.py!}
```

////
{* docs_src/arguments/help/tutorial007_an.py hl[8,12] *}

Then, if you check the `--help` option, you will see a default panel named "`Arguments`" for the *CLI arguments* that don't have a custom `rich_help_panel`.

Expand Down Expand Up @@ -380,27 +238,7 @@ If you want, you can make a *CLI argument* **not** show up in the `Arguments` se

You will probably not want to do this normally, but it's possible:

//// tab | Python 3.7+

```Python hl_lines="5"
{!> ../docs_src/arguments/help/tutorial008_an.py!}
```

////

//// tab | Python 3.7+ non-Annotated

/// tip

Prefer to use the `Annotated` version if possible.

///

```Python hl_lines="4"
{!> ../docs_src/arguments/help/tutorial008.py!}
```

////
{* docs_src/arguments/help/tutorial008_an.py hl[5] *}

Check it:

Expand Down
Loading
Loading