YAML with Schema
A developer can choose to additionally validate the input that a user gives in a YAML file through a schema. For more information on the version of schema that is implemented here, see the documentation.
Here is an example of a schema file for the above example.
$schema: "http://json-schema.org/draft-04/schema#"
type: object
properties:
meta:
type: string
fun:
type: bool
A schema must contain a link to the original definition, here given as a link, and a description of each variable. In this case, the schema is simple. It is describing an object with two properties (variables), meta
, and fun
. It succinctly gives the expected type declaration for these variables, which can be validated at run time.
To include this in the above report with yamldoc
, set the -s
flag.
yamldoc test/yaml/basic.yaml -s test/schema/basic.schema
Which outputs:
Configuration Parameters Reference
Any information about this page goes here.
Key Value Type Information meta
"Data"
string Here is some meta data. fun
True
bool And here is some more split over a couple of
lines.
Generated by yamldoc v0.1.2 on 2020-10-06
The difference between these two reports is the inclusion of the Type
column.
Modifying the Title and Description
Though the title and description of this page can easily be edited after it is generated, we also include a special declaration in the schema file to modify these easily.
Edit the schema file from before and add the following lines:
$schema: "http://json-schema.org/draft-04/schema#"
_yamldoc_title: My Awesome Title
_yamldoc_description: This can be a long string or paragraph talking about your parameters and describing how to use them. You can use line breaks too, you just have to write them manually.<br><br> Isn't that cool?
type: object
properties:
meta:
type: string
fun:
type: bool
Which gives
My Awesome Title
This can be a long string or paragraph talking about your parameters and describing how to use them. You can use line breaks too, you just have to write them manually.
Isn't that cool?
Key Value Type Information meta
"Data"
string Here is some meta data. fun
True
bool And here is some more split over a couple of
lines.
Generated by yamldoc v0.1.2 on 2020-10-06