cppalliance
feat: generate YAML schema for config
This PR extends generate-config-info.py to generate a YAML/JSON schema for the config file. As explained in the issue, this can be used to provide autocompletion and linting. The "YAML schema" is just a JSON schema.
Currently, the schema is committed to the repo. I'm not sure if that's desired. The main upside of this is, that users can link to the schema using (raw) GitHub links. This allows linking to tags, but most importantly it allows linking to specific commits. However, there's now duplicate information in the repo. CI ensures the schema is always up-to-date, though.
Alternatively, this could be done as part of the Antora build (probably, I'm not that familiar with it).
Closes #700.
Is this a standard format for validating the fields, or are there competing formats?
JSON-schema is the de-facto standard for many config-languages (i.e. not just JSON), since it's so versatile. In addition to YAML, it's also used for TOML (e.g. in taplo - schema for Cargo.toml).
It's the same format as the schema for vcpkg manifest files, right?
Yes, in JSON the standard is to specify a "$schema". At least on Microsoft's documentation, they guide users to use the schema from GitHub.
We can't guarantee the same for
mrdocs.schema.json. Is there a way to check that the resulting file is at least valid? Some tool or something?
That's mostly what I'm trying to do with the check in CI. An alternative could be to have a separate script, run that one in CI, and check if the output changed (with Git).
Or should the original config.json file follow the specification directly at some point in the future? Is there a way to associate categories with options in the specification?
Unfortunately, there's no way of having categories for options in a JSON schema. Furthermore, the current config.json has a few options that specify "command-line-only".
That's mostly what I'm trying to do with the check-in CI. An alternative could be to have a separate script, run that one in CI, and check if the output changed (with Git).
I see. Unless there's a tool to check if the file is valid, checking if the file has been touched or changed does not provide much additional value. We could remove the test for now.
I considered using the meta schema to check if the resulting file matches it. But we can go with what we have for now. Whoever is pushing a new commit should check if the file changed. I still believe it's possible to use the metaschema of the specification.
I'll at least create an issue. I saw this list of tools, but I haven't investigated it yet.
Unfortunately, there's no way of having categories for options in a JSON schema. Furthermore, the current config.json has a few options that specify "command-line-only".
I see. Some fields could contain extra information, so using the same file for both things could reduce redundancy and implicitly ensure we're testing the file. That's unfortunate.
An automated preview of the documentation is available at https://701.mrdocs.prtest2.cppalliance.org/index.html
An automated preview of the documentation is available at https://701.mrdocs.prtest2.cppalliance.org/index.html
An automated preview of the documentation is available at https://701.mrdocs.prtest2.cppalliance.org/index.html
I've updated the branch to make sure we're talking about the same thing.
- Only the draft-07 is supported by RedHat's LSP (https://redirect.github.com/redhat-developer/yaml-language-server/issues/780)
- I found that JetBrains IDEs support YAML schemas as well. They use a different syntax that has also been proposed for RedHat's LSP (https://redirect.github.com/redhat-developer/yaml-language-server/issues/959). I opened a PR to support this (https://redirect.github.com/redhat-developer/yaml-language-server/pull/992) but I don't think it will be merged in the near future.
- The schema is generated from
util/generate-yaml-schema.py(can run in any directory).
I've updated the branch to make sure we're talking about the same thing.
Nice. Thanks. All issues are solved then. Let's see if it passes CI, and we'll be good to go. We can open issues for whatever smaller issues we find or want to investigate.
An automated preview of the documentation is available at https://701.mrdocs.prtest2.cppalliance.org/index.html