Document Single Tables

This recipe shows how to document specific tables on different pages or sections, rather than listing all tables at once.

Configuration

In your mkdocs.yml:

plugins:
  - sqlalchemy:
      base_class: "single_tables.models.Base"
      app_path: "src"

Usage

You can document individual tables by specifying the table parameter in the tag.

users.md:

# User Documentation

{% sqlalchemy table="users" %}

posts.md:

# Post Documentation

{% sqlalchemy table="posts" %}

---

Result

Users Table

Table: users

column	type	nullable	default	primary_key	unique	foreign_key
id	INTEGER	❌		✔️	❌
username	VARCHAR(50)	❌		❌	✔️
email	VARCHAR(120)	❌		❌	✔️
is_active	BOOLEAN	✔️	True	❌	❌
created_at	DATETIME	✔️	utcnow	❌	❌

Indexes: None

Constraints:

• uq_users_username (UniqueConstraint)
• pk_users (PrimaryKeyConstraint)
• uq_users_email (UniqueConstraint)

Posts Table

Table: posts

column	type	nullable	default	primary_key	unique	foreign_key
id	INTEGER	❌		✔️	❌
title	VARCHAR(200)	❌		❌	❌
content	TEXT	✔️		❌	❌
is_published	BOOLEAN	✔️	False	❌	❌
user_id	INTEGER	✔️		❌	❌	users.id
created_at	DATETIME	✔️	utcnow	❌	❌
updated_at	DATETIME	✔️	utcnow	❌	❌

Indexes:

• ix_posts_updated_at: updated_at

Constraints:

• pk_posts (PrimaryKeyConstraint)
• fk_posts_user_id_users (ForeignKeyConstraint)