Update mkdocstrings config to render Pydantic field metadata

.github/workflows/docs.yml

@@ -33,7 +33,7 @@ jobs:
 
       - name: Install dependencies
         run: |
-          pip install zensical mkdocstrings-python markdown-exec[ansi]
+          pip install zensical mkdocstrings-python markdown-exec[ansi] griffe-pydantic
           pip install pytest pytest-cov pytest-r-snapshot
           pip install matplotlib python-docx pypdf
           pip install -e '.[all]'

CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## rtflite (development version)
+
+### Documentation
+
+- Update mkdocstrings settings to render Pydantic field metadata
+  via `griffe-pydantic` in API reference docs (#189).
+- Declare `RTFDocument._table_space` as a Pydantic private attribute to
+  prevent mkdocstrings render errors in static mode (#189).
+
 ## rtflite 2.5.2
 
 ### Documentation

docs/changelog.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## rtflite (development version)
+
+### Documentation
+
+- Update mkdocstrings settings to render Pydantic field metadata
+  via `griffe-pydantic` in API reference docs (#189).
+- Declare `RTFDocument._table_space` as a Pydantic private attribute to
+  prevent mkdocstrings render errors in static mode (#189).
+
 ## rtflite 2.5.2
 
 ### Documentation

docs/stylesheets/extra.css

@@ -16,25 +16,9 @@
     font-style: italic;
 }
 
-@font-face {
-    font-display: swap;
-    font-family: "JetBrains Mono";
-    src: url("../assets/JetBrainsMono-Variable.woff2") format("woff2");
-    font-weight: 100 800;
-    font-style: normal;
-}
-
-@font-face {
-    font-display: swap;
-    font-family: "JetBrains Mono";
-    src: url("../assets/JetBrainsMono-Italic-Variable.woff2") format("woff2");
-    font-weight: 100 800;
-    font-style: italic;
-}
-
 :root {
     --md-text-font: "Source Sans 3", system-ui, -apple-system, "Segoe UI", Roboto, "Helvetica Neue", Arial, "Noto Sans", "Liberation Sans", sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol", "Noto Color Emoji";
-    --md-code-font: "JetBrains Mono", ui-monospace, SFMono-Regular, "SF Mono", Menlo, Consolas, "Liberation Mono", monospace;
+    --md-code-font: ui-monospace, SFMono-Regular, "SF Mono", Menlo, Consolas, "Liberation Mono", monospace;
 }
 
 body {
@@ -55,6 +39,7 @@ body {
 
 .md-nav {
     font-size: 1rem;
+    line-height: 1.15;
 }
 
 .md-nav__item--section>.md-nav__link {
@@ -66,7 +51,11 @@ body {
 }
 
 .md-nav__item--nested .md-nav__icon::after {
-    height: 150%;
+    height: 1.5;
+}
+
+.md-ellipsis:has(.doc-symbol) {
+    font-size: 0.7em;
 }
 
 /* Content */
@@ -109,6 +98,18 @@ h4 code {
     font-size: 0.8rem;
 }
 
+h2.doc-heading {
+    font-size: 1rem;
+}
+
+h3.doc-heading {
+    font-size: 0.9rem;
+}
+
+.doc-contents.first>details>summary {
+    line-height: 1.5;
+}
+
 /* Banner */
 
 .md-banner {

pyproject.toml

@@ -106,6 +106,7 @@ dev = [
     "zensical>=0.0.15",
     "mkdocstrings-python>=1.12.2",
     "markdown-exec[ansi]>=1.11.0",
+    "griffe-pydantic>=1.1.8",
     "ruff>=0.7.4",
     "isort>=5.13.2",
     "mypy>=1.17.1",

src/rtflite/encode.py

@@ -10,7 +10,14 @@
 from pathlib import Path
 
 import polars as pl
-from pydantic import BaseModel, ConfigDict, Field, field_validator, model_validator
+from pydantic import (
+    BaseModel,
+    ConfigDict,
+    Field,
+    PrivateAttr,
+    field_validator,
+    model_validator,
+)
 
 from .convert import LibreOfficeConverter
 from .input import (
@@ -122,6 +129,7 @@ class RTFDocument(BaseModel):
     """
 
     model_config = ConfigDict(arbitrary_types_allowed=True)
+    _table_space: int = PrivateAttr(default=0)
 
     # Core data
     df: pl.DataFrame | list[pl.DataFrame] | None = Field(

src/rtflite/input.py

@@ -247,7 +247,7 @@ class RTFPage(BaseModel):
             Defaults to "double" for closure.
 
     Note:
-        The nrow parameter represents the total row capacity of a page,
+        The `nrow` parameter represents the total row capacity of a page,
         not just data rows. Plan accordingly when setting this value.
     """
 
@@ -717,8 +717,8 @@ class RTFColumnHeader(TableAttributes):
 
     Note:
         - Headers automatically repeat on each page in multi-page documents
-        - Use col_rel_width to create spanning headers
-        - Border styles from RTFPage are applied to the first row
+        - Use `col_rel_width` to create spanning headers
+        - Border styles from `RTFPage` are applied to the first row
     """
 
     model_config = ConfigDict(arbitrary_types_allowed=True)
@@ -833,10 +833,11 @@ class RTFBody(TableAttributes):
         ```
 
     Note:
-        When using subline_by:
+        When using `subline_by`:
+
         - The specified columns are removed from the table display
         - Values appear as paragraph headers before each section
-        - Pagination is automatically enabled (new_page=True)
+        - Pagination is automatically enabled (`new_page=True`)
         - Formatting attributes apply uniformly to the entire table
     """
 

zensical.toml

@@ -123,9 +123,30 @@ default_handler = "python"
 paths = ["src"]
 
 [project.plugins.mkdocstrings.handlers.python.options]
+extensions = [{ griffe_pydantic = { schema = true } }]
+filters = ["!^_"]
+# Important for griffe_pydantic to render Pydantic models
+force_inspection = false
 inherited_members = true
+members_order = "source"
+merge_init_into_class = true
+separate_signature = true
 show_root_heading = true
+show_signature_annotations = true
 show_source = false
+signature_crossrefs = true
+show_symbol_type_heading = true
+show_symbol_type_toc = true
+
+[project.plugins.mkdocstrings.handlers.python.options.docstring_options]
+ignore_init_summary = true
+
+[[project.plugins.mkdocstrings.handlers.python.import]]
+url = "https://docs.python.org/3/objects.inv"
+domains = ["py", "std"]
+
+[[project.plugins.mkdocstrings.handlers.python.import]]
+url = "https://typing-extensions.readthedocs.io/en/latest/objects.inv"
 
 # ----------------------------------------------------------------------------
 # Section for configuring markdown-exec plugin