Help: Generate presets JSON schema, documentation
Replace the CMake presets schema.json with a YAML document, from which
both the JSON schema and (most of) the reST documentation are generated.
This achieves three main goals. First, the YAML document is much closer
to being human-readable than the JSON schema. Second, the JSON and reST
prose (when the latter differs) are contained in the same file, in most
cases adjacent (and at worst, still nearby) rather than in separate
files, which should greatly facilitate keeping the two in sync. Third,
changes are monumentally easier, as changes merely need to annotate the
version(s) to which variants apply, rather than creating entirely
separate schema trees for each variant.
Since requiring Python as part of the build process is not desired,
the outputs are kept in the source repository. This is consistent with
other areas which are seldom updated and require special tools, such as
the lexer.
While this does not represent any functional change for users, some
grammatical edits and other such editorial improvements have been made
in the process of transferring everything to the new YAML. However,
these are mainly incidental rather than representative of an attempt at
a thorough editorial pass.
Finally, for clarity, monkey-patch `sphing.domains.changesets` and add
additional 'version modified' directives with slightly tweaked text to
identify changes to the presets schema. These are nearly identical to
the built-in directives, but use the text 'in presets version N' rather
than 'in version N[.N]'.
31 files changed