sphinx-config-schema#

sphinx-config-schema is a Sphinx extension that renders a JSON schema as a copyable TOML, YAML, or JSON example. Each key in the example shows the description of that setting as a tooltip, via sphinx-tippy, and links to itself so that it can be shared as a permalink.

This is useful for tools that read their configuration from a file, such as a [tool.*] table in pyproject.toml, and that generate a JSON schema for it, for instance for editor completion.

Installation#

pip install sphinx-config-schema

Then add the extension to the extensions list in your conf.py. It loads sphinx_tippy automatically:

conf.py#

extensions = [
    "sphinx_config_schema",
]

Usage#

The config-schema directive takes the path to a JSON schema file, relative to the current document or, with a leading /, to the documentation source directory. The optional table option sets the dotted path of the table under which the settings appear, caption adds a caption to the code block, format selects the output format, and header-titles titles references to TOML tables with their header:

MyST

```{config-schema} example.schema.json
:caption: pyproject.toml
:table: tool.example
:format: toml
:header-titles:
```

reST

.. config-schema:: example.schema.json
    :caption: pyproject.toml
    :table: tool.example
    :format: toml
    :header-titles:

The format option renders the example as yaml or json instead of the default toml. Settings are then nested by indentation instead of grouped under table headers. The tabs below show the same example schema in each format. Hover over a key to see what it does:

TOML

pyproject.toml#

[tool.example]
output = "build"
verbose = false
log-level = "warning"
# color = "auto"
exclude = []
env = {}

[tool.example.server]
host = "example.org"
port = 8080
headers = { Cache-Control = "no-cache", Content-Language = "en" }

YAML

config.yaml#

output: build
verbose: false
log-level: warning
color: null
exclude: []
env: {}
server:
  host: example.org
  port: 8080
  headers: {Cache-Control: no-cache, Content-Language: en}

JSON

config.json#

{
  "output": "build",
  "verbose": false,
  "log-level": "warning",
  "color": null,
  "exclude": [],
  "env": {},
  "server": {
    "host": "example.org",
    "port": 8080,
    "headers": {"Cache-Control": "no-cache", "Content-Language": "en"}
  }
}

The schema controls how the configuration is rendered:

Each setting shows its default or, if it has no usable default, its first non-null example or enum choice. Enum choices are also collected from anyOf and oneOf alternatives and local $ref references, unless an alternative accepts any value of its type, as in a nullable boolean. An empty list or table default counts as a placeholder and yields to an example. Settings without a usable value are omitted, or reported as errors when the strict flag is enabled.
A free-form table, an object with additionalProperties but no properties, shows its default or example like any other setting, such as server.headers. Without one, it appears as an empty table, such as env, so that readers see that it exists.
Settings with a null default keep that default in YAML and JSON. Since TOML has no null value, the example is commented out there, so copying the block does not enable an optional setting. For instance, color has a nullable enum and a null default, so the TOML tab shows # color = "auto".
Objects with their own properties become nested tables, including objects reached through local $ref references such as those generated by pydantic.
Each key has a tooltip containing its description, its actual default, allowed enum values, and any examples other than the value shown. Text in double or single backticks in descriptions renders as inline code, and a blank line starts a new paragraph. The tooltip of the last component of the table path shows the schema’s top-level description.
Keys listed under required get an asterisk in the example and a required badge in their tooltip, such as server.host. The asterisk is not copied with the example. Both can be restyled through the config-schema-required and config-schema-badge CSS classes.
Each key links to itself and can be referenced.

Other output formats#

The example is built from regular docutils nodes, so it also appears in other output formats, such as plain text and LaTeX. There, each key becomes a label that can be referenced. In LaTeX output, the example is a highlighted code block with its caption, like any other code block. Tooltips only appear in HTML. Instead of the asterisk, the line of a required key ends in a # required comment, except in JSON, which has no comments.

This documentation is also available as PDF, built with the LaTeX builder.

Directive reference#

.. config-schema:: path#

Render the JSON schema at path as a configuration example. The path is relative to the current document or, with a leading /, to the documentation source directory.

:caption: text (text)#: Caption of the code block, typically the name of the configuration file.

:format: toml, yaml or json (``toml`` (default), ``yaml`` or ``json``)#: Serialization format of the example.

:header-titles: (flag)#: Title references to the tables of a TOML example with their header, such as [tool.example.server], instead of the key path. Has no effect in YAML and JSON, which have no table headers.

:name: text (text)#: Name the example so it can be referenced with an explicit title using the config-schema:option role. Option and nested-table labels use this name as a prefix instead of adding a format suffix. Names must be unique across the documentation; reusing a name on the same page produces a warning.

:strict: (flag)#: Report settings that have no default, examples, or enum as an error instead of leaving them out.

:table: dotted.path (text)#: Dotted path of the table under which the settings appear, such as tool.example.

:config-schema:option:#: Link to a key of a config-schema example as inline code. See Referencing options for label syntax and title formatting.

:cfg:#: Short alias of config-schema:option.

sphinx-config-schema#

Installation#

Usage#

Referencing options#

Other output formats#

Directive reference#