Skip to content

sphinx-config-schema 0.0.1

Choose a tag to compare

@github-actions github-actions released this 29 Oct 22:34
· 17 commits to main since this release
Immutable release. Only release title and notes can be modified.
dbe6143

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-schema

Then 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 = 8080

Highlights:

  • Render as TOML, YAML, or JSON with the format option
  • Fill in values from default or examples, and list enum values and other examples in the tooltip
  • Resolve local $ref definitions, such as the ones that pydantic generates, into nested tables
  • Report settings without a default or example as an error with the strict flag
  • 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.