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.
cmd/ob-docgengenerates 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.mdxis the one reference page left that has a structuredsource 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
driversmap ininternal/app/services.goand they match exactly — 11 in code, 11 documented,no drift today. So this is not a bug report.
But the
driverstruct holds considerably more than a name, and none of itreaches the page:
image— the repository, e.g.clickhouse/clickhouse-server,getmeili/meilisearchport— the service's own port, which is what goes in the connection stringdataPath— where durable data lives in the container, and empty means thedriver stores nothing worth keeping
health— the container health check, whose absence is whyneedsdegradesto "started" rather than pretending
scheme— how the client URL is builtThat 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.
driversis unexported, so this needs either an exported accessor or exportingthe 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.mdxhas no single structured source. Which commandsupports which output mode is decided per command in the CLI, so generating it
would mean inferring behaviour rather than reading a declaration.
status/capabilities.mdxis authored on purpose.docs/README.mdalready saysthe 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.