config_reference

mkdocs_terok.config_reference

Pydantic model rendering engine for config reference documentation.

Provides functions to render Pydantic v2 BaseModel classes as Markdown tables, annotated YAML examples, and JSON Schema dumps. The consumer keeps its own models and field docs; only the rendering logic lives here.

.. note:: Pydantic is imported at module level. This module is only useful to consumers that have Pydantic installed — import failure is acceptable for projects that don't use this feature.

render_json_schema(model_class, *, title='')

Render the JSON Schema for a Pydantic model.

Parameters:

Name	Type	Description	Default
model_class	type[BaseModel]	The Pydantic model class.	required
title	str	Optional title to inject into the schema.	''

Returns:

Type	Description
str	Pretty-printed JSON Schema string.

Source code in src/mkdocs_terok/config_reference.py

def render_json_schema(
    model_class: type[BaseModel],
    *,
    title: str = "",
) -> str:
    """Render the JSON Schema for a Pydantic model.

    Args:
        model_class: The Pydantic model class.
        title: Optional title to inject into the schema.

    Returns:
        Pretty-printed JSON Schema string.
    """
    schema = model_class.model_json_schema(mode="validation")
    schema["$schema"] = "https://json-schema.org/draft/2020-12/schema"
    if title:
        schema["title"] = title
    return json.dumps(schema, indent=2) + "\n"

render_model_tables(model_class, *, field_docs=None, heading_level=3)

Render Markdown tables for all sections of a Pydantic model.

Parameters:

Name	Type	Description	Default
model_class	type[BaseModel]	The top-level Pydantic model class.	required
field_docs	dict[str, str] | None	Mapping of "section.field" dotpaths to descriptions.	None
heading_level	int	Starting heading level for section headers.	3

Returns:

Type	Description
str	Markdown string with section tables.

Source code in src/mkdocs_terok/config_reference.py

def render_model_tables(
    model_class: type[BaseModel],
    *,
    field_docs: dict[str, str] | None = None,
    heading_level: int = 3,
) -> str:
    """Render Markdown tables for all sections of a Pydantic model.

    Args:
        model_class: The top-level Pydantic model class.
        field_docs: Mapping of ``"section.field"`` dotpaths to descriptions.
        heading_level: Starting heading level for section headers.

    Returns:
        Markdown string with section tables.
    """
    if field_docs is None:
        field_docs = {}
    buf = io.StringIO()

    leaf_fields: list[tuple[str, FieldInfo]] = []
    sections: list[tuple[str, type[BaseModel]]] = []

    for name, field_info in model_class.model_fields.items():
        sub_model = _unwrap_section_model(field_info)
        if sub_model is not None:
            sections.append((name, sub_model))
        else:
            leaf_fields.append((name, field_info))

    if leaf_fields:
        hashes = "#" * heading_level
        buf.write(f"{hashes} Top-level keys\n\n")
        buf.write("| Key | Type | Default | Description |\n")
        buf.write("|-----|------|---------|-------------|\n")
        for name, fi in leaf_fields:
            type_s = _type_str(fi)
            default_s = _default_repr(fi)
            desc = _md_escape(field_docs.get(name, fi.description or ""))
            buf.write(f"| `{name}` | {type_s} | {default_s} | {desc} |\n")
        buf.write("\n")

    for name, sub_model in sections:
        _render_section_table(
            buf, sub_model, f"{name}.", field_docs=field_docs, heading_level=heading_level
        )

    return buf.getvalue()

render_yaml_example(model_class, *, field_docs=None)

Render a full annotated YAML example for a Pydantic model.

Parameters:

Name	Type	Description	Default
model_class	type[BaseModel]	The Pydantic model class.	required
field_docs	dict[str, str] | None	Mapping of "section.field" dotpaths to descriptions.	None

Returns:

Type	Description
str	YAML string with annotated fields and descriptions.

Source code in src/mkdocs_terok/config_reference.py

def render_yaml_example(
    model_class: type[BaseModel],
    *,
    field_docs: dict[str, str] | None = None,
) -> str:
    """Render a full annotated YAML example for a Pydantic model.

    Args:
        model_class: The Pydantic model class.
        field_docs: Mapping of ``"section.field"`` dotpaths to descriptions.

    Returns:
        YAML string with annotated fields and descriptions.
    """
    buf = io.StringIO()
    _render_yaml_fields(buf, model_class, field_docs=field_docs)
    return buf.getvalue()