YAML Configuration File¶
The current YAML configuration file is in beta state. There are many options and features that it doesn’t support yet. This document will serve as a design document for discuss how to implement the missing features.
Finish the spec to include all the missing options
Have consistency around the spec
Proper documentation for the end user
Allow to specify the spec’s version used on the YAML file
Collect/show metadata about the YAML file and build configuration
Promote the adoption of the configuration file
No all the RTD settings are applicable to the YAML file, others are applicable for each build (or version), and others for the global project.
Not applicable settings¶
Those settings can’t be on the YAML file because: may depend for the initial project setup, are planned to be removed, security and privacy reasons.
Privacy level (this feature is planned to be removed 1)
Project description (this feature is planned to be removed 2)
To keep consistency with the per-version settings and avoid confusion, this settings will not be stored in the YAML file and will be stored in the database only.
Those configurations will be read from the YAML file in the current version that is being built.
Several settings are already implemented and documented on https://docs.readthedocs.io/en/latest/yaml-config.html. So, they aren’t covered with much detail here.
Project installation (virtual env, requirements file, sphinx configuration file, etc)
Additional builds (pdf, epub)
The file format is based on the YAML spec 1.2 3 (latest version on the time of this writing).
The file must be on the root directory of the repository, and must be named as:
The spec of the configuration file must use this conventions.
to indicate an empty list
nullto indicate a null value
all(internal string keyword) to indicate that all options are included on a list with predetermined choices.
falseas only options on boolean fields
The current spec is documented on https://docs.readthedocs.io/en/latest/yaml-config.html. It will be used as base for the future spec. The spec will be written using a validation schema such as https://json-schema-everywhere.github.io/yaml.
Versioning the spec¶
The version of the spec that the user wants to use will be specified on the YAML file. The spec only will have mayor versions (1.0, not 1.2) 4. For keeping compatibility with older projects using a configuration file without a version, the latest compatible version will be used (1.0).
Adoption of the configuration file¶
When a user creates a new project or it’s on the settings page, we could suggest her/him an example of a functional configuration file with a minimal setup. And making clear where to put global configurations.
For users that already have a project, we can suggest him/her a configuration file on each build based on the current settings.
Configuration file and database¶
The settings used in the build from the configuration file (and other metadata) needs to be stored in the database, this is for later usage only, not to populate existing fields.
The build process¶
The repository is updated
Checkout to the current version
Retrieve the settings from the database
Try to parse the YAML file (the build fails if there is an error)
Merge the both settings (YAML file and database)
The version is built according to the settings
The settings used to build the documentation can be seen by the user
Current repository which contains the code related to the configuration file: https://github.com/readthedocs/readthedocs-build