Privileged issue

• I'm @tiangolo or he asked me directly to create an issue here.

Issue Content

This is a good first contribution. 🤓

The code examples shown in the docs are actual Python files. They are even tested in CI, that's why you can always copy paste an example and it will always work, the example is tested.

The way those examples are included in the docs used a specific format. But now there's a new format available that is much simpler and easier to use than the previous one, in particular in complex cases, for example when there are examples in multiple versions of Python.

But not all the docs have the new format yet. The docs should use the new format to include examples. That is the task. 🤓

It should be done as one PR per page updated.

Simple Example

Before, the format was like:

```Python hl_lines="3"
{!../../docs_src/first_steps/tutorial001.py!}
```

Now the new format looks like:

{* ../../docs_src/first_steps/tutorial001.py hl[3] *}

• Instead of {! and !} it uses {* and *}
• It no longer has a line above with:

```Python

• And it no longer has a line below with:

```

• The highlight is no longer a line with e.g. hl_lines="3" (to highlight line 3), but instead in the same line there's a hl[3].

An example PR: #12552

Multiple Python Versions

There are some cases where there are variants of the same example for multiple versions of Python, or for using Annotated or not.

In those cases, the current include examples have syntax for tabs, and notes saying Annotated should be preferred. For example:

//// tab | Python 3.9+

```Python hl_lines="4  8  12"
{!> ../../docs_src/security/tutorial006_an_py39.py!}
```

////

//// tab | Python 3.8+

```Python hl_lines="2  7  11"
{!> ../../docs_src/security/tutorial006_an.py!}
```

////

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

/// tip

Prefer to use the `Annotated` version if possible.

///

```Python hl_lines="2  6  10"
{!> ../../docs_src/security/tutorial006.py!}
```

////

In these cases, it should be updated to only include the first one (the others will be included automatically 😎 ):

{* ../../docs_src/security/tutorial006_an_py39.py hl[4,8,12] *}

• The syntax for tabs is also removed, all the other variants are included automatically.
• The highlight lines are included for that same first file, the fragment with hl_lines="4 8 12" is replaced with hl[4,8,12]

An example PR: #12553

Highlight Lines

Simple Lines

When there's a fragment like:

hl_lines="4  8  12"

That means it is highlighting the lines 4, 8, and 12.

The new syntax is on the same include line:

hl[4,8,12]

• It separates individual lines by commas.
• It uses hl, with square brackets around.

Line Ranges

When there are line ranges, like:

hl_lines="4-6"

That means it is highlighting lines from 4 to 6 (so, 4, 5, and 6).

The new syntax uses : instead of - for the ranges:

hl[4:6]

Multiple Highlights

There are some highlights that include individual lines and also line ranges, for example the old syntax was:

hl_lines="2  4-6  8-11  13"

That means it is highlighting:

• Line 2
• Lines from 4 to 6 (so, 4, 5, and 6)
• Lines from 8 to 11 (so, 8, 9, 10, and 11)
• Line 13

The new syntax separates by commas instead of spaces:

hl[2,4:6,8:11,13]

Include Specific Lines

In some cases, there are specific lines included instead of the entire file.

For example, the old syntax was:

```Python hl_lines="7"
{!> ../../docs_src/separate_openapi_schemas/tutorial001_py310.py[ln:1-7]!}

# Code below omitted 👇
```

In this example, the lines included are from line 1 to line 7 (lines 1, 2, 3, 4, 5, 6, 7). In the old syntax, it's defined with the fragment:

[ln:1-7]

In the new syntax, the included code from above would be:

{* ../../docs_src/separate_openapi_schemas/tutorial001_py310.py ln[1:7] hl[7] *}

• The lines to include that were defined with the fragment [ln:1-7], are now defined with ln[1:7]

The new syntax ln as in ln[1:7] also supports multiple lines and ranges to include.

Comments Between Line Ranges

In the old syntax, when there are ranges of code included, there are comments like:

# Code below omitted 👇

The new syntax generates those comments automatically based on the line ranges.

Real Example

A more real example of the include with the old syntax looked like this:

//// tab | Python 3.10+

```Python hl_lines="7"
{!> ../../docs_src/separate_openapi_schemas/tutorial001_py310.py[ln:1-7]!}

# Code below omitted 👇
```

<details>
<summary>👀 Full file preview</summary>

```Python
{!> ../../docs_src/separate_openapi_schemas/tutorial001_py310.py!}
```

</details>

////

//// tab | Python 3.9+

```Python hl_lines="9"
{!> ../../docs_src/separate_openapi_schemas/tutorial001_py39.py[ln:1-9]!}

# Code below omitted 👇
```

<details>
<summary>👀 Full file preview</summary>

```Python
{!> ../../docs_src/separate_openapi_schemas/tutorial001_py39.py!}
```

</details>

////

//// tab | Python 3.8+

```Python hl_lines="9"
{!> ../../docs_src/separate_openapi_schemas/tutorial001.py[ln:1-9]!}

# Code below omitted 👇
```

<details>
<summary>👀 Full file preview</summary>

```Python
{!> ../../docs_src/separate_openapi_schemas/tutorial001.py!}
```

</details>

////

In the new syntax, that is replaced with this:

{* ../../docs_src/separate_openapi_schemas/tutorial001_py310.py ln[1:7] hl[7] *}

• The only file that needs to be included and defined is the first one, and the lines to include and highlight are also needed for the first file.
• All the other file includes, full file preview, comments, etc. are generated automatically.

An example PR: #12555

Help

Do you want to help? Please do!

Remember it should be done as one PR per page updated.

If you see a page that doesn't fit these cases, leave it as is, I'll take care of it later.

Before submitting a PR, check if there's another one already handling that file.

Please name the PR including the file path, for example:

📝 Update includes for `docs/tutorial/create-db-and-table.md`