schema#

import sphinx_config_schema.schema

Collect the settings of a JSON schema that the example shows.

NO_DEFAULT#

Default of a Setting whose schema has none, as None is a valid default.

class Setting(table: tuple[str, ...], name: str, value: Any, description: str, examples: tuple[Any, ...] = (), allowed: tuple[Any, ...] = (), default: Any = NO_DEFAULT, value_source: Literal['default', 'example', 'enum', 'placeholder'] | None = None, required: bool = False, _anchor_prefix: str = '', _anchor_suffix: str = '')[source]#

Bases: object

One key-value pair in the generated example.

table: tuple[str, ...][source]#: Keys of the enclosing tables, one per nesting level, such as ("tool", "demo") for [tool.demo]; empty at the top level.

name: str[source]#: Unquoted key of the setting within its table.

value: Any[source]#: Value shown in the example, which value_source traces back to the schema.

description: str[source]#: Description from the schema for the tooltip, in which inline literals become code.

examples: tuple[Any, ...] = ()[source]#: Example values from the schema, listed in the tooltip unless value shows them.

allowed: tuple[Any, ...] = ()[source]#: The values that the schema allows for this setting through enum.

default: Any = NO_DEFAULT[source]#: The actual schema default, kept separate from the displayed example.

value_source: Literal['default', 'example', 'enum', 'placeholder'] | None = None[source]#

Origin of value; unset for settings constructed without schema metadata.

A "placeholder" is the empty mapping shown for a free-form table, an object with additionalProperties but neither properties nor a value to show.

required: bool = False[source]#: Whether the enclosing object lists the key under required.

property path: tuple[str, ...][source]#: Full path of the key, including its name.

property anchor: str[source]#: HTML ID of the key, from which its ref label is formed.

class Table(table: tuple[str, ...], name: str, description: str, required: bool = False, _anchor_prefix: str = '', _anchor_suffix: str = '')[source]#

Bases: object

A nested table in the generated example, which holds settings of its own.

table: tuple[str, ...][source]#: Keys of the enclosing tables, as in Setting.table.

name: str[source]#: Unquoted key of the table within its parent.

description: str[source]#: Description from the schema for the tooltip, as in Setting.description.

required: bool = False[source]#: Whether the enclosing object lists the table under required.

property path: tuple[str, ...][source]#: Full path of the table, including its name.

property anchor: str[source]#: HTML ID of the key, from which its ref label is formed.

Entry = sphinx_config_schema.schema.Setting | sphinx_config_schema.schema.Table#: A key in the generated example.

iter_settings(schema: dict[str, Any], table: tuple[str, ...] = (), *, strict: bool = False) → Iterator[Entry][source]#

Collect the settings with a default or example value from a JSON schema.

Settings without a usable value are skipped, or reported with a ValueError after all other settings have been collected if strict is set. Nested tables are yielded as a Table, so that their key can carry a description as well. So is the last part of table, with the description of the schema itself.

>>> schema = {
...     "description": "Demo settings.",
...     "properties": {
...         "name": {"description": "Project name.", "examples": ["demo"]},
...         "optional": {"type": "string"},
...     },
... }
>>> for entry in iter_settings(schema, table=("tool", "demo")):
...     print(entry)
Table(table=('tool',), name='demo', description='Demo settings.')
Setting(table=('tool', 'demo'), name='name', value='demo', description='Project name.')
>>> list(iter_settings(schema, strict=True))
Traceback (most recent call last):
    ...
ValueError: Settings without a default or example: optional