sphinx-config-schema 0.0.4

⚠️ Enhancements and optimizations

• Render backtick references in config-schema tooltips as code instead of raw backticks (#38)
• Split tooltip descriptions into paragraphs at blank lines instead of showing literal \n\n (#40)

📝 Documentation

• Link JSON Schema keywords like default and anyOf to their reference pages (#38)

The full changelog as commits can be found here.

sphinx-config-schema 0.0.3

✨ New features

• Adds a header-titles flag that titles references to TOML tables with their header, such as [tool.example] (#36)

⚠️ Enhancements and optimizations

• Tables without settings of their own, such as tool.pwa, can now be referenced (#36)

⚠️ Changes that may affect behavior

• References to the table of an example show its full path instead of only its last key (#36)

🖱️ Developer Experience

• VS Code formats JSON, YAML, Markdown, CSS, and HTML files with Prettier (#36)

The full changelog as commits can be found here.

sphinx-config-schema 0.0.2

✨ New features

• Configuration keys rendered by config-schema are Sphinx labels that ref can link to (#11)
• New config-schema:option role links to a key and renders it as inline code (#17)
• Registers cfg as a short alias of the config-schema:option role (#23)

⚠️ Enhancements and optimizations

• Optional enum settings without a default show their first choice as an example (#7)
• Option references with a leading . resolve by key suffix, and ~ shortens the title (#23)
• Free-form tables without properties render as an empty table instead of disappearing (#29)
• Required keys are marked with an asterisk in the example and a badge in the tooltip (#32)

⚠️ API changes

• Option labels separate key levels with dots, as in settings.output instead of settings-output (#13)

⚠️ Changes that may affect behavior

• Anchors of unnamed examples end with the format, so old #…-output links no longer jump to the key (#11)
• References with a leading . match by key suffix instead of as exact labels (#23)

🐛 Bug fixes

• Enum choices resolve through local $ref and anyOf or oneOf alternatives (#7)
• A null default no longer renders an inferred example as if it were the default (#10)
• Examples in LaTeX and PDF output get syntax highlighting, a frame, and a caption (#15)
• Nullable non-enum fields no longer list null as their only allowed value (#34)

📝 Documentation

• Landing page shows PyPI, Python version, CI, and license badges (#5)
• Documents enum choices as the final fallback for generated examples (#7)
• New "Referencing options" section shows the reference syntax in MyST and reST (#11)
• Documentation is also available as a PDF (#15)
• API pages reflect the split into schema, render, codeblock, and tooltips submodules (#24)

🔨 Maintenance

• Helpers such as render() and iter_settings() move into dedicated submodules (#24)

🖱️ Developer Experience

• Test coverage is reported to Codecov and must stay above 95% (#22)
• Tests are organized per module as nested pytest-describe behavior specifications (#24)

The full changelog as commits can be found here.

sphinx-config-schema 0.0.1

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.