openapi generated doc image

Author: hadrien

README.md

@@ -186,21 +186,21 @@ async def create_user(new_hero: HeroBase, session: Session):
 
 ### Database
 
-💡 This example uses an `SQLite` database for simplicity.
+💡 This example uses an `SQLite` database for simplicity: `FastSQLA` is compatible with
+all asynchronous db drivers that `SQLAlchemy` is compatible with.
 
-`FastSQLA` is compatible with all asynchronous db drivers that `SQLAlchemy` is
-compatible with.
+Let's create an `SQLite` database using `sqlite3` and insert 12 rows in the `hero` table:
 
-Let's create an `SQLite` database using `sqlite3`:
 ```bash
 sqlite3 db.sqlite <<EOF
+-- Create Table hero
 CREATE TABLE hero (
     id              INTEGER PRIMARY KEY AUTOINCREMENT,
-    name            TEXT NOT NULL UNIQUE, -- Hero name (e.g., Superman)
+    name            TEXT NOT NULL UNIQUE, -- Unique hero name (e.g., Superman)
     secret_identity TEXT NOT NULL         -- Secret identity (e.g., Clark Kent)
 );
 
--- Insert heroes with hero name and secret identity
+-- Insert heroes with their name and secret identity
 INSERT INTO hero (name, secret_identity) VALUES ('Superman',        'Clark Kent');
 INSERT INTO hero (name, secret_identity) VALUES ('Batman',          'Bruce Wayne');
 INSERT INTO hero (name, secret_identity) VALUES ('Wonder Woman',    'Diana Prince');
@@ -218,10 +218,14 @@ EOF
 
 ### Run the app
 
-Let's install required dependencies & run the app:
+Let's install required dependencies:
 ```bash
 pip install uvicorn aiosqlite fastsqla
-sqlalchemy_url=sqlite+aiosqlite:///db.sqlite?check_same_thread=false uvicorn example:app
+```
+Let's run the app:
+```
+sqlalchemy_url=sqlite+aiosqlite:///db.sqlite?check_same_thread=false \
+  uvicorn example:app
 ```
 
 ### Check the result
@@ -254,6 +258,13 @@ Returns:
 }
 ```
 
+You can also check the generated openapi doc by opening your browser to
+[http://127.0.0.1:8000/docs](http://127.0.0.1:8000/docs).
+
+![OpenAPI generated documentation of the example API](images/example-openapi-generated-doc.png)
+
+
+
 ## License
 
 This project is licensed under the terms of the [MIT license](https://github.com/hadrien/FastSQLA/blob/main/LICENSE).

docs/configuration.md

@@ -11,22 +11,23 @@ variables, with each parameter name prefixed by **`SQLALCHEMY_`**.
 
 !!! note
 
-    FastSQLA is case-insensitive when reading environment variables, so parameter names
-    prefixed with **`SQLALCHEMY_`** can be provided in any letter case.
+    FastSQLA is **case-insensitive** when reading environment variables, so parameter
+    names prefixed with **`SQLALCHEMY_`** can be provided in any letter case.
 
 ## Examples
 
-1.  :simple-postgresql: PostgreSQL url using [`asyncpg`][sqlalchemy.dialects.postgresql.asyncpg]
-    driver with a [`pool_recycle`][sqlalchemy.create_engine.params.pool_recycle] of 30
-    minutes:
+1.  :simple-postgresql: PostgreSQL url using
+    [`asyncpg`][sqlalchemy.dialects.postgresql.asyncpg] driver with a
+    [`pool_recycle`][sqlalchemy.create_engine.params.pool_recycle] of 30 minutes:
 
     ```bash
     export SQLALCHEMY_URL=postgresql+asyncpg://postgres@localhost
     export SQLALCHEMY_POOL_RECYCLE=1800
     ```
 
-2.  :simple-sqlite: SQLite db file using [`aiosqlite`][sqlalchemy.dialects.sqlite.aiosqlite]
-    driver with a [`pool_size`][sqlalchemy.create_engine.params.pool_size] of 50:
+2.  :simple-sqlite: SQLite db file using
+    [`aiosqlite`][sqlalchemy.dialects.sqlite.aiosqlite] driver with a
+    [`pool_size`][sqlalchemy.create_engine.params.pool_size] of 50:
 
     ```bash
     export sqlalchemy_url=sqlite+aiosqlite:////tmp/test.db?check_same_thread=false

docs/images/example-openapi-generated-doc.png

@@ -16,6 +16,7 @@ theme:
     logo: material/database
   name: material
   features:
+    - admonition
     - announce.dismiss
     - content.code.annotate
     - content.code.copy
@@ -49,8 +50,8 @@ theme:
         name: Switch to system preference
 
 plugins:
-  - search
   - autorefs
+  - glightbox
   - mkdocstrings:
       enable_inventory: true
       handlers:
@@ -59,14 +60,18 @@ plugins:
           - https://docs.python.org/3/objects.inv
           - https://docs.sqlalchemy.org/en/20/objects.inv
           - https://fastapi.tiangolo.com/objects.inv
+  - search
 
 markdown_extensions:
   - admonition
-  - pymdownx.details
-  - pymdownx.superfences
   - attr_list
+  - md_in_html
+  - pymdownx.blocks.caption
+  - pymdownx.details
   - pymdownx.emoji:
       emoji_index: !!python/name:material.extensions.emoji.twemoji
       emoji_generator: !!python/name:material.extensions.emoji.to_svg
+  - pymdownx.superfences
   - toc:
       permalink: true
+

mkdocs.yml

@@ -43,7 +43,11 @@ Issues = "https://github.com/hadrien/fastsqla/issues"
 Changelog = "https://github.com/hadrien/fastsqla/releases"
 
 [project.optional-dependencies]
-docs = ["mkdocs-material>=9.5.50", "mkdocstrings[python]>=0.27.0"]
+docs = [
+    "mkdocs-glightbox>=0.4.0",
+    "mkdocs-material>=9.5.50",
+    "mkdocstrings[python]>=0.27.0",
+]
 
 [tool.uv]
 package = true