Repository navigation
sphinx-config-schema 0.0.1
·
17 commits
to main
since this release
Immutable
release. Only release title and notes can be modified.
First release of sphinx-config-schema, a Sphinx extension that renders a JSON schema as a copyable TOML, YAML, or JSON configuration example. Each key shows the description of its setting as a tooltip and links to itself as a permalink. This is useful for tools that read their settings from a file, such as a [tool.*] table in pyproject.toml, and that already generate a JSON schema for editor completion. See the documentation for a live example.
Installation
pip install sphinx-config-schemaThen add the extension to your conf.py (details):
extensions = [
"sphinx_config_schema",
]Usage
Given a schema like this:
{
"description": "Settings of the example tool.",
"type": "object",
"properties": {
"output": {
"description": "Directory to which the tool writes its results.",
"type": "string",
"default": "build"
},
"server": {
"description": "Settings of the server that hosts the output.",
"type": "object",
"properties": {
"port": {
"description": "Port on which the server listens.",
"type": "integer",
"default": 8080
}
}
}
}
}the config-schema directive
```{config-schema} example.schema.json
:caption: pyproject.toml
:table: tool.example
```renders a code block in which every key has a tooltip and a permalink, such as #tool-example-output:
[tool.example]
output = "build"
[tool.example.server]
port = 8080Highlights:
- Render as TOML, YAML, or JSON with the
formatoption - Fill in values from
defaultorexamples, and listenumvalues and other examples in the tooltip - Resolve local
$refdefinitions, such as the ones that pydantic generates, into nested tables - Report settings without a default or example as an error with the
strictflag - Works in both reStructuredText and MyST Markdown, and in non-HTML builders such as LaTeX
See the usage guide and the directive reference for all options.