Build chart parameter docs from values.schema.json
#15827
Conversation
jedcunningham
requested review from
ashb,
dimberman,
kaxil,
mik-laj,
potiuk and
vikramkoka
as code owners
boring-cyborg
bot
added
area:dev-tools
area:helm-chart
|
The Workflow run is cancelling this PR. It has some failed jobs matching ^Pylint$,^Static checks,^Build docs$,^Spell check docs$,^Provider packages,^Checks: Helm tests$,^Test OpenAPI*. |
|
The Workflow run is cancelling this PR. It has some failed jobs matching ^Pylint$,^Static checks,^Build docs$,^Spell check docs$,^Provider packages,^Checks: Helm tests$,^Test OpenAPI*. |
This automatically builds the chart parameter docs page from the `values.schema.json`. It also tracks and enforces that the defaults in `values.yaml` and `values.schema.json` match. The parameter docs page now has different sections, which are set in the schema file under `docs_schema`. That key is required for top level properties in the schema file, and optional otherwise as the parents `docs_schema` is used as a default. We also now have a schema for our `values.schema.json` in `values_schema.schema.json` which enforces the items we need to build the docs are set appropriately: `docs_schema`, `default`, and `description`.
jedcunningham
force-pushed
the
chart-param-docs
branch
from
6a7e655
to
ff70a5f
Compare
| @@ -2,68 +2,112 @@ | |||
| "$schema": "http://json-schema.org/draft-07/schema", | |||
| "description": "Default values for airflow. Declare variables to be passed into your templates.", | |||
| "type": "object", | |||
| "docs_section_order": [ | |||
There was a problem hiding this comment.
What do you think to use the x- prefix to denote that this field is not part of the official JSON Schema specification? This is not required in our case, but I think it will improve readability.
There was a problem hiding this comment.
I'm okay with that. Maybe x-docsSectionOrder and x-docsSection? Feels like we should use the x- prefix everywhere for non standard fields?
There was a problem hiding this comment.
Let's do it in the follow-up PR please
|
How is a user meant to actually view the documentation following this change? Trying to view the file on github just shows the jinja code instead of the list of parameters. |
|
For the sake of cross linking, I relied here: #26914 (comment) |
This automatically builds the chart parameter docs page from the
values.schema.json. It also tracks and enforces that the defaults invalues.yamlandvalues.schema.jsonmatch.The parameter docs page now has different sections, which are set in the
schema file under
docs_schema. That key is required for top levelproperties in the schema file, and optional otherwise as the parents
docs_schemais used as a default.We also now have a schema for our
values.schema.jsoninvalues_schema.schema.jsonwhich enforces the items we need to buildthe docs are set appropriately:
docs_schema,default, anddescription.Closes #15771