Docs site config: Zensical features, Markdown extensions, API reference options and a strict build #701

Recommendation table

Griffe extensions

mkdocstrings-python options

Current: docstring_style="google", show_source=true, show_root_heading=true, show_root_full_path=false, show_category_heading=true, show_if_no_docstring=true, members_order="source"; inventories=[python].

Recommended zensical.toml block (verified building with exit 0, "No issues found")

[project.plugins.mkdocstrings.handlers.python]
paths = ["src"]
inventories = [
  "https://docs.python.org/3/objects.inv",
  "https://docs.pydantic.dev/latest/objects.inv",
]

[project.plugins.mkdocstrings.handlers.python.options]
docstring_style = "google"
docstring_options = { ignore_init_summary = true }
merge_init_into_class = true
show_source = true                 # consider false (3x smaller API pages)
show_root_heading = true
show_root_full_path = false
show_category_heading = true
show_if_no_docstring = true
members_order = "source"
filters = "public"
separate_signature = true
show_signature_annotations = true
signature_crossrefs = true
show_symbol_type_heading = true
show_symbol_type_toc = true
scoped_crossrefs = true
relative_crossrefs = true
summary = true
backlinks = "tree"
extensions = ["griffe_inherited_docstrings"]

Add griffe-inherited-docstrings to the docs dependency group in pyproject.toml (next to zensical / mkdocstrings-python, lines 61–62 and 81–82).

Local options, also verified:

::: ferro.Field
    options:
      show_overloads: false
      parameter_headings: true

::: ferro.FerroError
    options:
      show_inheritance_diagram: true

If griffe-pydantic is adopted, add it with the pydantic_settings preload. Do not preload pydantic, because that crashes the build:

extensions = ["griffe_inherited_docstrings", { griffe_pydantic = { schema = false } }]
preload_modules = ["pydantic_settings"]

Details

griffe-pydantic (Consider)

What changed in the build (static mode):

• PoolConfig, DatabaseSettings, Row and Model get the pydantic-model label and a Config section (frozen: True, extra: forbid, and for Model from_attributes, use_attribute_docstrings, arbitrary_types_allowed). PoolConfig and DatabaseSettings also get Fields and Validators lists, and fields and validators get pydantic-field / pydantic-validator labels.
• FerroSettings (a BaseSettings) is not detected unless preload_modules = ["pydantic_settings"] is set. With the preload it is detected (5 models instead of 3 on the connection page).

Caveats that keep it at Consider:

1. Field constraints vanish from the displayed value. max_connections = PydanticField(default=5, ge=1) renders as max_connections = 5, and name = Field(min_length=1) renders as name. Today the constraint is visible. Unless each field's docstring states the constraint, docs lose information.
2. A private validator leaks. Model's Validators section lists _validate_required_foreign_keys.
3. schema = true silently turned the extension off in static mode: the output was identical to having no extension. A JSON schema would need dynamic import of ferro, which means building the Rust extension in the docs job.
4. preload_modules = ["pydantic"] crashes the build (TypeError: 'NoneType' object is not iterable), so it can't be combined with unpack_typeddict's workaround.

Sphinx roles are a bigger rendering bug than any extension

Google-style docstrings across src/ferro contain 284 :class: / :meth: / :func: / :attr: roles. mkdocstrings doesn't interpret them, so Model's own docstring shows "as a tuple of :class: ~ferro.checks.Check objects". With scoped_crossrefs / relative_crossrefs on, they can become [Check][ferro.checks.Check] or [Check][]. The conversion is a separate docs task. No Griffe extension converts Sphinx roles (griffe-sphinx handles only #: comments).

Deprecations

ferro/_deprecations.py defines deprecated(reason=, since=, remove_in=, reference=), which wraps with functools.wraps and warnings.warn. Nothing uses it (grep @deprecated finds nothing), and griffe can't see it either way. Because Ferro requires Python ≥ 3.13, warnings.deprecated is in the stdlib. If the helper is rewritten to return warnings.deprecated(message)(obj), then type checkers flag call sites (PEP 702) and griffe_warnings_deprecated renders the admonition. Adopt the extension in that same change. Until then it is a no-op (built: 0 changed lines).

Remaining griffe warnings

models.py:730/758/817/850 warn No type or annotation for parameter '**fields'. Fix this in the source by annotating **fields: Any. Don't silence it with warn_missing_types = false.

Effects measured

• Options set (site-opts): doc-signature blocks went from 20 to 315, internal autorefs from 67 to 439, external from 245 to 1343, backlink nodes from 0 to 577, and there are 300 heading badges and 740 TOC badges. The anchor ids are identical to the baseline except that the 18 *.__init__ anchors are gone (merged into the class).
• inherited-docstrings: only relationships changed. Relation.all / Relation.first gained their Returns and Examples.
• Page weights (bytes): model 607,879 / 422,914 (options) / 173,623 (show_source off); queries 996,893 / 667,150 / 288,532.

Verified by building vs unverified

Verified (Zensical build exit 0 in the scratch copy, output text-diffed):

• All recommended global options together, griffe_inherited_docstrings, and the pydantic inventory: build reports "No issues found".
• Local show_overloads: false, parameter_headings: true (anchor ferro.Field(index) present), and show_inheritance_diagram: true on FerroError (one pre.mermaid emitted).
• griffe-pydantic (static, schema=false), with and without the pydantic_settings preload. Its schema=true mode is a no-op. A pydantic preload crashes the build.
• unpack_typeddict and griffe_typingdoc crash without a preload. With preload_modules=["pydantic"], unpack_typeddict builds.
• griffe_warnings_deprecated, griffe_generics, griffe_modernized_annotations, griffe_fieldz and griffe_public_redundant_aliases load cleanly and change nothing.
• show_source=false, inherited_members=true, docstring_section_style="list": build clean (sizes above).
• Zensical passes handler options through unchanged to upstream mkdocstrings (read zensical/compat/mkdocstrings.py), and its theme CSS has rules for doc-symbol, doc-backlink, doc-label and mermaid.

Unverified:

• Visual rendering in a browser: badge appearance, the client-side Mermaid render of the inheritance diagram, and backlink layout at phone width. Only HTML structure and CSS rule presence were checked.
• griffe_inherited_method_crossrefs, griffe_runtime_objects, griffe_sphinx, griffe_autodocstringstyle, docstring_inheritance and griffe_fastapi were not installed or built (judged from their docs and the codebase grep). The docstring-inheritance page returned HTTP 503.
• griffe-pydantic in dynamic mode (needs the compiled ferro._core).
• None of these builds used a docs job identical to CI. pydantic-settings>=2.0 is a Ferro runtime dependency (pyproject line 12), so the preload should resolve there.

TL;DR

1. A rendering bug, found by this audit: about 130 snippet sections render with 8 (or 4) spaces of leading indentation. Most # --8<-- [start:x] markers in docs/examples/*.py sit inside async def main():, so the embedded code shows up indented on the page. For example, guide/queries.md:65 embeds predicates.py:filtering and the page shows adults = await User.... One option fixes it: pymdownx.snippets.dedent_subsections = true. I checked this in the trial build.
2. Tabs: give them readable anchors and link them site-wide. I-7 puts "Assignment / Annotated" tab pairs on every model example. Today their ids are __tabbed_1_1. Setting tabbed.combine_header_slug and slugify gives defining-a-model-assignment. The theme feature content.tabs.link (a theme setting, not an extension) makes one click on "Annotated" switch every tab pair on the site and remembers the choice across pages.
3. Glossary tooltips: add abbr plus snippets.auto_append with docs/includes/abbreviations.md for DDL, RLS, FK, PK, GUC, FFI, GIL, IR and similar terms. In the prose outside code, SQL appears 104 times, DDL 53, FK 27, GUC 5, RLS 6 and FFI 6. Pair it with the theme feature content.tooltips.
4. MagicLink for #NNN issue refs. CHANGELOG.md is embedded through changelog.md and has about 20 bare refs like (#647) that render as plain text today, plus api/queries.md:34. In the trial build this produced 94 issue links on the changelog page.
5. The 12.x upgrade breaks nothing in the current config. Both the current config and the proposed one build. The only warning is the existing mkdocstrings autoref pydantic.fields.FieldInfo warning.

Recommendation table

Line refs are relative to docs/pages/ unless noted.

Proposed full markdown_extensions block

This is the tail of zensical.toml (it replaces everything from [project.markdown_extensions.attr_list] on). The Adopt set is abbr, magiclink, the snippets dedent_subsections and auto_append options, the tabbed slug options and toc.permalink_title. def_list and footnotes are commented "Consider" lines; uncomment them on first use.

# --- Python-Markdown core ---
[project.markdown_extensions.abbr]
[project.markdown_extensions.attr_list]
[project.markdown_extensions.md_in_html]
[project.markdown_extensions.admonition]
[project.markdown_extensions.tables]
# Consider, enable on first use:
# [project.markdown_extensions.def_list]
# [project.markdown_extensions.footnotes]

[project.markdown_extensions.toc]
permalink = true
permalink_title = "Anchor link to this section"

# --- pymdown-extensions ---
[project.markdown_extensions.pymdownx.details]
[project.markdown_extensions.pymdownx.inlinehilite]
[project.markdown_extensions.pymdownx.keys]
[project.markdown_extensions.pymdownx.mark]
[project.markdown_extensions.pymdownx.smartsymbols]

[project.markdown_extensions.pymdownx.magiclink]
provider = "github"
user = "syn54x"
repo = "ferro-orm"
repo_url_shorthand = true      # #123 -> issue, !123 -> PR, SHAs -> commit
repo_url_shortener = true      # bare github.com/syn54x/ferro-orm/issues/291 -> "#291"
normalize_issue_symbols = true # render !123 as #123

[project.markdown_extensions.pymdownx.superfences]
custom_fences = [
  { name = "mermaid", class = "mermaid", format = "pymdownx.superfences.fence_code_format" },
]

[project.markdown_extensions.pymdownx.snippets]
base_path = ["."]
check_paths = true
dedent_subsections = true                          # fixes indented section embeds
auto_append = ["docs/includes/abbreviations.md"]   # glossary, outside docs_dir

[project.markdown_extensions.pymdownx.highlight]
anchor_linenums = true
line_spans = "__span"
pygments_lang_class = true

[project.markdown_extensions.pymdownx.tabbed]
alternate_style = true
combine_header_slug = true
slugify = { object = "pymdownx.slugs.slugify", kwds = { case = "lower" } }

[project.markdown_extensions.pymdownx.emoji]
emoji_index = "zensical.extensions.emoji.twemoji"
emoji_generator = "zensical.extensions.emoji.to_svg"

Theme features that pair with the above (add to [project.theme].features):

  "content.tabs.link",   # one Assignment/Annotated choice applies site-wide
  "content.tooltips",    # styled tooltips for abbr titles, permalinks, copy button

A starting glossary, docs/includes/abbreviations.md (Zensical recommends keeping it outside docs_dir, here docs/pages, so it is not built as a page; check_paths = true makes a missing file a build error):

*[ADR]: Architecture Decision Record
*[ASGI]: Asynchronous Server Gateway Interface
*[CRUD]: Create, Read, Update, Delete
*[DBAPI]: Python Database API (PEP 249)
*[DDL]: Data Definition Language: CREATE, ALTER and DROP statements
*[DML]: Data Manipulation Language: INSERT, UPDATE and DELETE statements
*[FFI]: Foreign Function Interface: the Python-to-Rust boundary
*[FK]: Foreign key
*[FKs]: Foreign keys
*[GIL]: Global Interpreter Lock
*[GUC]: Grand Unified Configuration: a Postgres runtime setting
*[GUCs]: Grand Unified Configuration settings (Postgres runtime settings)
*[IR]: Intermediate representation
*[JSONB]: Postgres binary JSON type
*[ORM]: Object-Relational Mapper
*[PK]: Primary key
*[RLS]: Row-Level Security (Postgres)
*[TTY]: Terminal
*[UUID]: Universally Unique Identifier

SQL, API, JSON and URL are left out on purpose: the readers know them, and they appear so often that underlining every one adds noise. abbr never touches code spans or fences (verified). Abbreviations are case-sensitive whole-word matches, plural forms need their own entries (FKs, GUCs), and they apply in the changelog too (72 hits there in the trial build).

Build verification

• Current repo config (uv run --no-sync zensical build --clean in the repo): builds in about 2.3s. The one warning is unresolved autoref pydantic.fields.FieldInfo in api/fields.md (pre-existing, mkdocstrings), plus griffe notes about **fields annotations in src/ferro/models.py:730,758,817,850. Because of that warning, --strict fails both before and after the change, so it is not a regression. I rebuilt the repo's site/ with the original config afterwards.
• Trial (/private/tmp/claude-501/-Users-taylor-orca-workspaces-ferro-orm-Docs-rewrite/46c7594e-13a3-4dbd-b539-6be8e5f4b3e1/scratchpad/pymdownx-trial/): a copy of zensical.toml with the block above (with def_list and footnotes on, to prove they load), the two theme features and the glossary file, plus copies of docs/pages, docs/examples, src, CHANGELOG.md, CONTRIBUTING.md and README.md, built with uv run --no-sync --project <repo> zensical build --clean. Result: builds cleanly, same single pre-existing warning, same page set. Checked in the output:
  • guide/queries/ "Filtering with where()": the code now starts at column 0 (adults = await User...). Before, it had 8 leading spaces.
  • changelog/: 94 magiclink-issue links; guide/row-level-security/: <abbr> on GUC, GUCs, RLS, DDL, ASGI, ADR.
  • guide/models-and-fields/: tab labels for="defining-a-model-assignment" / "defining-a-model-annotated" (was __tabbed_1_1 / __tabbed_1_2).
  • Duplicate HTML ids: 8 api/* pages have duplicate __codelineno-0-N / __span-0-N ids (mkdocstrings show_source = true source blocks all numbered from 0). This happens the same way in the baseline build, so the change did not cause it. The tab slugs added no duplicate ids. Worth a separate ticket.
• Zensical's build supports -f/--config-file, but docs_dir and snippets base_path resolve against the project directory, so I ran the trial from a copy of the project tree.

12.x upgrade notes (from 10.21)

None of these break the current config. In detail:

• 12.0: BetterEm, Mark, Caret and Tilde rewritten. Emphasis is CommonMark-compliant, and ==mark== now works mid-word by default (smart_mark = true restores the old rule). Ferro enables mark only. Every == sits in code, so nothing changes. BetterEm, caret and tilde are not enabled.
• 12.0: removed deprecated slug functions uslugify* and gfm*. The config doesn't use them. The proposed tabbed slug uses pymdownx.slugs.slugify with kwds, the supported form.
• 12.0: removed old-style custom emoji index logic. Ferro uses zensical.extensions.emoji.twemoji and to_svg, Zensical's supported index and generator, and the build is fine.
• 12.0: removed Arithmatex inline_*/fence_* format options. Not used.
• 12.0: Details and admonition titles handle headers specially. No impact.
• 12.0 new: BracketSpan. Skip (see the table).
• 11.0 (breaking, B64 only): relative paths are restricted to base_path. Not used.
• 11.0.x: performance fixes in InlineHilite, Keys, Blocks.HTML, BetterEm, Tilde, Caret and MagicLink. Free.
• 12.1: SuperFences custom fences accept an optional reset. The mermaid fence doesn't need it.
• 12.2: Highlight auto_title_map entries and SuperFences title_mode="html" allow HTML in code-block titles. Optional; useful only if file-name titles need markup. Tilde/Caret punctuation option. Python 3.15 support.
• 12.3: BetterEm punctuation option. Not relevant.
• Snippets security (10.21.3): fixed a directory-traversal regression with restrict_base_path (default on). Keep the default.
• Also from 10.20: the new quotes extension. Skip.

Other observations (not extension config)

• guide/queries.md:63 says the lambda parameter is "t by convention", but I-8 says to name it after the model (user), and the snippet right below uses user. This is a docs-content fix.
• concepts/architecture.md:43-50: the "Implementation status (2026-06-26)" note is a blockquote. A !!! note would match the house style, and its claims may be stale after the one-planner work in AGENTS.md I-1.

1. What changed between 0.0.45 and 0.0.71

Breaking or changed defaults

New features (with "since" version)

Not yet in Zensical: native versioning (on the roadmap; today only the mike fork), the privacy and optimize plugins (planned / in progress), git-revision-date and git-authors (planned), and gen-files (unsupported). Analytics is "being overhauled" (the setup/analytics page).

2. Feature table

"Ferro today" describes the current zensical.toml. "Config" is the TOML to add.

3. Proposed diff to zensical.toml

Also delete docs/pages/guide/migrations.md, because the redirects plugin replaces it. Feature list is alphabetized. search.suggest is removed. This exact file built clean (see §4).

@@ -82,20 +82,34 @@
 [project.theme]
 features = [
-  "navigation.tabs",
-  "navigation.sections",
+  "content.action.copy",
+  "content.action.edit",
+  "content.action.view",
+  "content.code.annotate",
+  "content.code.copy",
+  "content.code.select",
+  "content.footnote.tooltips",
+  "content.tabs.link",
+  "content.tooltips",
   "navigation.expand",
+  "navigation.footer",
+  "navigation.instant",
+  "navigation.instant.progress",
+  "navigation.path",
+  "navigation.sections",
+  "navigation.tabs",
   "navigation.top",
-  "toc.follow",
-  "search.suggest",
+  "navigation.tracking",
   "search.highlight",
-  "content.code.copy",
-  "content.code.annotate",
-  "content.action.edit",
-  "content.action.view",
+  "toc.follow",
 ]

 [[project.theme.palette]]
+media = "(prefers-color-scheme)"
+toggle.icon = "lucide/sun-moon"
+toggle.name = "Switch to light mode"
+
+[[project.theme.palette]]
 media = "(prefers-color-scheme: light)"
 scheme = "light-rust"
 primary = "custom"
@@ -109,8 +123,61 @@
 primary = "custom"
 accent = "amber"
 toggle.icon = "lucide/moon"
-toggle.name = "Switch to light mode"
+toggle.name = "Switch to system preference"

+[project.extra]
+status.new = "Recently added"
+status.deprecated = "Deprecated"
+
+[[project.extra.social]]
+icon = "fontawesome/brands/github"
+link = "https://github.com/syn54x/ferro-orm"
+name = "Ferro on GitHub"
+
+[[project.extra.social]]
+icon = "fontawesome/brands/python"
+link = "https://pypi.org/project/ferro-orm/"
+name = "Ferro on PyPI"
+
+[project.plugins.llmstxt]
+markdown_description = "Ferro is an async Python ORM: Pydantic models, a Rust core, SQLite and Postgres."
+full_output = "llms-full.txt"
+
+[project.plugins.llmstxt.sections]
+"Start here" = [
+  "index.md",
+  "why-ferro.md",
+  "getting-started/installation.md",
+  "getting-started/quickstart.md",
+  "getting-started/next-steps.md",
+]
+"Guide" = ["guide/*.md", "guide/schema/*.md"]
+"How-to" = ["howto/*.md"]
+"Concepts" = ["concepts/*.md"]
+"Reference" = ["reference/*.md", "api/*.md"]
+"Community" = ["faq.md", "roadmap.md", "contributing.md"]
+
+[project.plugins.redirects.redirect_maps]
+"guide/migrations.md" = "guide/schema/overview.md"
+"guide/migrations.md#three-ways-to-manage-schema" = "guide/schema/overview.md#the-ladder"
+"guide/migrations.md#auto-migration" = "guide/schema/auto-migrate.md"
+"guide/migrations.md#creating-tables-with-auto_migratetrue" = "guide/schema/auto-migrate.md#creating-tables-with-auto_migratetrue"
+"guide/migrations.md#applying-column-changes

…(truncated; see the audit report)

</details>