Skip to content

Generate the service driver reference from the driver catalogue #103

Description

@vishr

cmd/ob-docgen generates the CLI reference (44 commands), the error catalogue
(135 codes) and the project-file fields (234 rows across 13 pages) — around 413
documented facts, gate-checked against the binary by just docs-generate-check.

reference/drivers.mdx is the one reference page left that has a structured
source and is still written by hand.

What the page says versus what the code holds

The page lists 11 driver names. I checked them against the drivers map in
internal/app/services.go and they match exactly — 11 in code, 11 documented,
no drift today. So this is not a bug report.

But the driver struct holds considerably more than a name, and none of it
reaches the page:

  • image — the repository, e.g. clickhouse/clickhouse-server, getmeili/meilisearch
  • port — the service's own port, which is what goes in the connection string
  • dataPath — where durable data lives in the container, and empty means the
    driver stores nothing worth keeping
  • health — the container health check, whose absence is why needs degrades
    to "started" rather than pretending
  • scheme — how the client URL is built

That is roughly 55 facts a reader currently has to get from the source, on a page
whose whole job is to answer "what do I get if I write driver: valkey".

Why it is worth generating rather than expanding by hand

Names are the slowest-moving attribute of a driver and the only one documented,
which is why nothing has drifted yet. Images, ports and health checks are the
fast-moving ones — a base image change or a health check that gains a flag would
not be visible to anyone reading the docs, and there is no check that would fail.

drivers is unexported, so this needs either an exported accessor or exporting
the map, the same way the field pages reach the schema.

Scope

This is the last item of any size. The other two hand-written reference pages
should stay that way, and it is worth saying why so nobody generates them by
reflex:

  • reference/policies.mdx has no single structured source. Which command
    supports which output mode is decided per command in the CLI, so generating it
    would mean inferring behaviour rather than reading a declaration.
  • status/capabilities.mdx is authored on purpose. docs/README.md already says
    the shipped / schema-only / intent-only marking "is a claim a reviewer should
    check rather than one the build can prove".

With drivers generated, onebox would be at roughly 468 of 468 — effectively all
of its machine-readable surface, with the two deliberate exceptions above.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions