service_catalog Extension

service_catalog is a custom Sphinx extension that generates the service catalog automatically from YAML data files.

It is the technical centrepiece of this docs platform: a single Python module that connects structured data, schema validation, and templating into the Sphinx build pipeline.

---

Source

The extension is a single file: extensions/service_catalog.py.

It hooks into Sphinx via the builder-inited event, which fires before any source files are read. This means the generated .md files are available to Sphinx as if they were hand-written.

---

API reference

service_catalog — Sphinx extension for the internal service catalog.

This extension reads YAML service definitions, validates them against a JSON Schema, and generates documentation pages automatically during the Sphinx build.

How it works:

        flowchart TD
    A["data/services/*.yaml"] -->|load & validate| B[service_catalog extension]
    C["schemas/service.schema.json"] -->|JSON Schema| B
    D["docs/_templates/service_page.md.jinja2"] -->|Jinja2| B
    B -->|generate| E["docs/catalog/generated/*.md"]
    E -->|sphinx-build| F[HTML site]
    

Configuration (in conf.py):

extensions = ["service_catalog"]

service_catalog_data_dir = "data/services"
service_catalog_schema = "schemas/service.schema.json"
service_catalog_output_dir = "docs/catalog/generated"
service_catalog_template = "docs/_templates/service_page.md.jinja2"

service_catalog.on_builder_inited(app: Sphinx) → None

Sphinx event handler: generate all catalog pages at build start.

Called by Sphinx on the builder-inited event, before any source files are read. Generates:

• One .md page per service in service_catalog_output_dir

• A catalog index page (index.md) in the same directory

Parameters:

app – The Sphinx application instance. Configuration values are read from app.config.

Raises:

ValueError – Propagated from _load_services() if any YAML file fails schema validation. This causes the build to fail with a clear error message.

service_catalog.setup(app: Sphinx) → dict

Register the extension with Sphinx.

Declares four configuration values (all overridable in conf.py) and connects on_builder_inited() to the builder-inited event.

Parameters:

app – The Sphinx application instance.

Returns:

Extension metadata dictionary required by Sphinx.