Tutorials

The following tutorials assumes knowledge of how to interact with files in a command line environment. Otherwise, basic Linux skills and an understanding of Python syntax will be an asset.

Flat YAML

The most common use case for this software will be to generate configuration for a flat file of configuration options. In this case, there are many parameters, each with a name, and a value. See below for a minimal example.

#' Here is some meta data.
meta: "Data"

#' And here is 
#' some more
#' split over
#' a couple of lines.
fun: True

Each value has a name, a colon, and a value. Above each value we have given meta data in a comment with a specific prefix #'. This can be whatever character you want, so long as it is consistent. You can give different prefix characters with the -c flag.

To create a report from this file, point yamldoc to it.

yamldoc test/yaml/basic.yaml

Which gives

Configuration Parameters Reference

Any information about this page goes here.

Key Value Information

meta "Data" Here is some meta data.

fun True And here is some more split over a couple of
lines.

Generated by yamldoc v0.1.2 on 2020-10-06

Notice how yamldoc intelligently joins and wraps long comments to fit inside the table. In later tutorials, we will see how to extend this and automatically embed the results in Sphinx documentation.

Key	Value	Information
`meta`	`"Data"`	Here is some meta data.
`fun`	`True`	And here is some more split over a couple of lines.