SQLModel + FastAPI Hero Tutorial Documentation - Multiple Improvements (Incorrect installation instructions for FastAPI, code omission improvements)

[ttepatti]

First Check

• I added a very descriptive title here.
• I used the GitHub search to find a similar question and didn't find it.
• I searched the SQLModel documentation, with the integrated search.
• I already searched in Google "How to X in SQLModel" and didn't find any information.
• I already read and followed all the tutorial in the docs and didn't find an answer.
• I already checked if it is not related to SQLModel but to Pydantic.
• I already checked if it is not related to SQLModel but to SQLAlchemy.

Commit to Help

• I commit to help with one of those options 👆

Example Code

(not applicable, as this item is referencing documentation issues - not programming bugs)

The referenced documentation is located within the SQLModel project here:

https://github.com/fastapi/sqlmodel/blob/main/docs/tutorial/fastapi/simple-hero-api.md

The rendered version of the referenced documentation can be seen on the SQLModel website here:

https://sqlmodel.tiangolo.com/tutorial/fastapi/simple-hero-api/#install-fastapi

Description

There are a number of issues I noted while following the SQLModel + FastAPI "Hero" tutorial. This tutorial is documented in the file 'simple-hero-api.md'.

They're relatively minor issues, but I figured fixing them would be important to help new people (like me! 😄 ) get into SQLModel/FastAPI/etc.

I've raised these as a discussion item here because the project specifically asks that new issues are not opened without prior authorization/posting here first. Please let me know if you'd prefer I shifted it over to an issue - I'd be happy to move it over as needed.

Issue 1 - Incorrect FastAPI Installation Instructions

The documented pip command to install FastAPI does not install the FastAPI CLI tool.

Later in the tutorial (specifically, on line 143 of simple-hero-api.md) the user is asked to run the FastAPI CLI tool to launch the application. Unfortunately, with the current pip installation method, the user will receive the error:

To use the fastapi command, please install "fastapi[standard]":
    pip install "fastapi[standard]"

Traceback (most recent call last):
... <error message snipped> ...

Issue 1 - Solution: Modify pip Installation Command for FastAPI

To solve the first issue raised with FastAPI's CLI, the following installation instruction in the tutorial should be modified:

$ pip install fastapi "uvicorn[standard]"

Following the FastAPI error's advice, It should be updated to:

$ pip install "fastapi[standard]" "uvicorn[standard]"

This will allow the FastAPI CLI tool to be used without any errors.

Issues 2 & 3 - Confusing Omissions of Code in Tutorial Code Blocks

• Step 1 of the tutorial (titled "SQLModel Code - Models, Engine") already says "code omitted above" and "code omitted below" - however, no code is omitted - it's the first step of the tutorial. The only omitted code is the code you write in the next steps.
• Step 2 of the tutorial (titled "FastAPI App") says "code here omitted" and "code below omitted" both above and below where it wants you to place the app = FastAPI() statement. This is confusing, because it implies that you have to place the app = FastAPI() line somewhere in the middle of the previously-written section of code. In reality, there is nothing below the app = FastAPI() statement yet, and it should be inserted at the current bottom of the file. So essentially, the example code block should not say "code below omitted", because there is nothing there.

Issues 2 & 3 - Investigation

Issues 2 & 3 both relate to the same thing - confusing use of "code omitted [above, below, etc.]" in the tutorial. I found that these aren't written by hand into the tutorial source, so I did some investigating:

I see that in the source of the tutorial files, code blocks are generated using inline references to source code files, such as the following (taken from line 59 of the simple-hero-api.md file)

{* ./docs_src/tutorial/fastapi/simple_hero_api/tutorial001_py310.py ln[1:2,23] hl[1,23] *}

This snippet generates a code block that includes lines 1, 2, and 23 (as instructed by ln[1:2,23]), and then highlights the new additions to the file (in this case, lines 1 and 23, as instructed by hl[1,23]). The resulting code block looks like the following:

As you can see, The "Code above omittted"-type statements are never intentionally invoked, but are added to the code block.

I did some additional digging into the mkdocs YAML configuration files in the root directory of the repository, but unfortunately I am not very familiar with mkdocs - I can't find exactly what mkdocs functionality or extension is responsible for the "code above omitted" type of statements. From what I can find it doesn't appear to be default functionality of MkDocs, so I'm assuming it is inserted by one of the extensions in use.

Issues 2 & 3 - Theoretical Solution

The fact that these markings likely come from a third-party plugin makes it a bit more difficult to fix - I am unsure if the functionality exists to remove the included statements in specific places.

Personally, I think an optimal solution would be to not show those "code omitted [place]" statements by default. Instead, being able to intentionally enable them through the markdown reference to the code block could be useful.

For example, to modify the above example, I wish it could be clarified with the following:

{* ./docs_src/tutorial/fastapi/simple_hero_api/tutorial001_py310.py ln[1:2,23] om[3,22] hl[1,23] *}

In this theoretical scenario, adding om[3,22] would cause a "code here omitted" reference specifically for lines 3 through 22. The rendered code block would look like the following:

from fastapi import FastAPI
from sqlmodel import Field, Session, SQLModel, create_engine, select

# Code here omitted 👈

app = FastAPI()

This helps to clarify that in the current tutorial context, no code should occur after app = FastAPI().

This finer-grained control over code omission pointers could make it much easier to provide clarity in rendered code blocks, while still not relying on hard-coded source code chunks directly in the markdown files. If anyone is able to provide information on what plugin or functionality is used to insert these statements into the tutorials, I'd be happy to raise this as a potential feature or improvement on their project.

In Conclusion...

Sorry for the massive wall of text, and thank you for reading! I'm just now getting into SQLModel and FastAPI for the first time, so this combined tutorial has been very helpful 😃 I thought it would be useful to bring up areas where I struggled or stumbled, as newbies to the project are the most likely to be reading these tutorials, and the most likely to be tripped up by small errors like these.

Thank you!

Operating System

Linux

Operating System Details

Ubuntu 24.04 LTS x64

SQLModel Version

0.0.24

Python Version

Python 3.13.2

Additional Context

No response