Update docs include syntax for source examples

[tiangolo]

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="1  4"
{!./docs_src/tutorial/create_db_and_table/tutorial001_py310.py!}
```

Now the new format looks like:

{* ./docs_src/tutorial/create_db_and_table/tutorial001_py310.py hl[1,4] *}

• 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].

Multiple Python Versions

In many cases 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.10+

```Python hl_lines="1  4"
{!./docs_src/tutorial/create_db_and_table/tutorial001_py310.py!}
```

////

//// tab | Python 3.7+

```Python hl_lines="3  6"
{!./docs_src/tutorial/create_db_and_table/tutorial001.py!}
```

////

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

{* ./docs_src/tutorial/create_db_and_table/tutorial001_py310.py hl[1,4] *}

• 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="1 4" is replaced with hl[1,4]

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="1  4"
{!./docs_src/tutorial/create_db_and_table/tutorial001_py310.py[ln:1-8]!}

# More code here later 👇
```

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

[ln:1-8]

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

{* ./docs_src/tutorial/create_db_and_table/tutorial001_py310.py ln[1:8] hl[1,4] *}

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

The new syntax ln as in ln[1:8] 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="1  4"
{!./docs_src/tutorial/create_db_and_table/tutorial001_py310.py[ln:1-8]!}

# More code here later 👇
```

////

//// tab | Python 3.7+

```Python hl_lines="3  6"
{!./docs_src/tutorial/create_db_and_table/tutorial001.py[ln:1-10]!}

# More code here later 👇
```

////

/// details | 👀 Full file preview

//// tab | Python 3.10+

```Python
{!./docs_src/tutorial/create_db_and_table/tutorial001_py310.py!}
```

////

//// tab | Python 3.7+

```Python
{!./docs_src/tutorial/create_db_and_table/tutorial001.py!}
```

////

///

In the new syntax, that is replaced with this:

{* ./docs_src/tutorial/create_db_and_table/tutorial001_py310.py ln[1:8] hl[1,4] *}

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

---

An example PR: #1149

Line Ranges and Highlights

In the old syntax, the hl_lines="15" refers to highlighting the resulting lines.

For example, with the old syntax:

```Python hl_lines="15"
# Code above omitted 👆

{!./docs_src/advanced/uuid/tutorial001_py310.py[ln:37-54]!}

# Code below omitted 👇
```

The result is rendered something like:

# Code above omitted 👆

def select_hero():
    with Session(engine) as session:
        hero_2 = Hero(name="Spider-Boy", secret_name="Pedro Parqueador")
        session.add(hero_2)
        session.commit()
        session.refresh(hero_2)
        hero_id = hero_2.id
        print("Created hero:")
        print(hero_2)
        print("Created hero ID:")
        print(hero_id)

        statement = select(Hero).where(Hero.id == hero_id)  # THIS LINE IS HIGHLIGHTED
        selected_hero = session.exec(statement).one()
        print("Selected hero:")
        print(selected_hero)
        print("Selected hero ID:")
        print(selected_hero.id)

# Code below omitted 👇

And the highlight would be on the line with the comment # THIS LINE IS HIGHLIGHTED.

If you count the lines in that snippet, the first line has:

# Code above omitted 👆

And the line 15 in that snippet has:

        statement = select(Hero).where(Hero.id == hero_id)  # THIS LINE IS HIGHLIGHTED

Not the entire source file was included, only lines 37 to 54. And that highlighted line inside of the source file is actually line 49. But the hl_lines="15" refers to the line 15 in the rendered snippet of code.

So, with the old syntax, when you want to highlight lines, you have to include the file and see the rendered result, count lines in the rendered document, and then mark the lines to highlight based on that result, wait for the reload to check if the line is correct, etc. ...it's a very slow process.

But with the new syntax, the number that you use is the line in the actual source file, so, if the line to highlight in the source file is line 49, that's what you define in the include:

{* ./docs_src/advanced/uuid/tutorial001_py310.py ln[37:54] hl[49] *}

This way it's easier to declare the lines or line ranges to include and the lines to highlight by just checking the source file. All the comments in between ranges and complex math will be done automatically.

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`

[szew404]

Hi, I can't run the project on my machine (MacOS).

I've followed the steps described in https://sqlmodel.tiangolo.com/contributing/

After successfully installing requirements.txt, I tried running the project as follows:

Executing python ./scripts/docs.py live or python3 ./scripts/docs.py live I get the following error:

ERROR   -  "cairosvg" Python module is installed, but it crashed with:
           no library called "cairo-2" was found
           no library called "cairo" was found
           no library called "libcairo-2" was found
           cannot load library 'libcairo.so.2': dlopen(libcairo.so.2, 0x0002): tried: 'libcairo.so.2' (no such file), '/opt/homebrew/lib/libcairo.so.2' (no such
           file), '/Users/fran/Developer/Learning/Python/SQLModel/sqlmodel/libcairo.so.2' (no such file).  Additionally, ctypes.util.find_library() did not manage to
           locate a library called 'libcairo.so.2'
           cannot load library 'libcairo.2.dylib': dlopen(libcairo.2.dylib, 0x0002): tried: 'libcairo.2.dylib' (no such file), '/opt/homebrew/lib/libcairo.2.dylib'
           (no such file), '/Users/fran/Developer/Learning/Python/SQLModel/sqlmodel/libcairo.2.dylib' (no such file).  Additionally, ctypes.util.find_library() did
           not manage to locate a library called 'libcairo.2.dylib'
           cannot load library 'libcairo-2.dll': dlopen(libcairo-2.dll, 0x0002): tried: 'libcairo-2.dll' (no such file), '/opt/homebrew/lib/libcairo-2.dll' (no such
           file), '/Users/fran/Developer/Learning/Python/SQLModel/sqlmodel/libcairo-2.dll' (no such file).  Additionally, ctypes.util.find_library() did not manage to
           locate a library called 'libcairo-2.dll'

           --> Check out the troubleshooting guide: https://t.ly/MfX6u

Aborted with a BuildError!

I've tried the alternatively way by running mkdocs serve --dev-addr 8008 but it returns the same error.

I have seen about the error at https://t.ly/MfX6u and tried every proposed solution but it still doesn't work.

Am I doing something wrong? Thanks for your time!

[tiangolo]

@szew404 I'm not on macOS but I infer you probably need to install Cairo apart from that: https://formulae.brew.sh/formula/cairo