YAML is a way to write nested data structures in plain text that is often used to specify configuration options for software. The acronym stands for “YAML Ain’t Markup Language,” but that’s misleading: YAML doesn’t use tags like HTML, but can still be quite fussy about what is allowed to appear where.
Throughout this book we use YAML to
configure our plotting script (Chapter 10),
continuous integration with Travis CI (Section 11.8),
software environment with
conda (Section 13.2.1),
and a documentation website with Read the Docs (Section 14.6.3).
While you don’t need to be an expert in YAML to complete tasks like these,
this appendix outlines some basics that can help make things easier.
A simple YAML file has one key-value pair on each line with a colon separating the key from the value:
the keys are
and the values are
and (hopefully) the number 1,
since most YAML implementations try to guess the type of data.
If we want to create a list of values without keys, we can write it either using square brackets (like a Python array) or dashed items (like a Markdown list), so:
are equivalent. (The indentation isn’t absolutely required in this case, but helps make the intention clear.) If we want to write entire paragraphs, we can use a marker to show that a value spans multiple lines:
We can also add comments using
# just as we do in many programming languages.
YAML is easy to understand when used this way, but it starts to get tricky as soon as sub-lists and sub-keys appear. For example, this is part of the YAML configuration file for formatting this book:
It corresponds to the following Python data structure: