Commit f92827c3 authored by Sarah White's avatar Sarah White Committed by Sarah White

edit playbook builder architecture guidebook

parent 730fc663
= Playbook Component Architecture
= Playbook Builder Component Architecture
== Context
......@@ -15,12 +15,12 @@ Therefore, the object that holds the data in the playbook needs to be transmitta
The playbook component takes a configuration file, which we call a [.term]_playbook spec_, as input.
A playbook spec can be created and used by anyone operating an Antora pipeline.
While the playbook spec is the primary means of configuration, audibles may be passed using either process arguments (i.e., command-line flags and switches), environment variables, or a combination of both.
Audibles overrides equivalent option values in the playbook spec.
Audibles override equivalent option values in the playbook spec.
Using a playbook spec as an input, the component should carry out the following operations:
* Read the playbook spec file
* Accept and apply any audibles (i.e., override options) passed by the user at runtime.
* Accept and apply any audibles (i.e., override options) passed by the user at runtime
* Validate the playbook spec
* Convert the playbook spec file into a transmittable model that the other pipeline components can use
......@@ -37,11 +37,11 @@ The playbook component should:
** By accepting these two parameters, the playbook builder can be used and tested independently of the CLI runtime environment.
** Within those parameters, a playbook spec file may be specified, which is a third (and the bulk) method of user input.
* Look for the specified playbook spec file composed in YAML, JSON, or CSON format
** When the data in these formats are read in, they become plain JavaScript objects
** When the data in these formats are read in, they become plain JavaScript objects.
* Apply audibles in the form of process arguments and environment variables
** The order of precedence for an option value is as follows (highest to lowest): process argument, environment variable, spec, default
** The order of precedence for an option value is as follows (highest to lowest): process argument, environment variable, spec, default.
* Validate the aggregate playbook spec values
** The validation step checks that the option value matches the expected data type and enforces required options
** The validation step checks that the option value matches the expected data type and enforces required options.
* Convert a valid playbook spec into a transmittable, well-defined, read-only data model that other pipeline components can use
.Inputs
......@@ -90,18 +90,18 @@ const sources = playbook.content.sources
The schema for the playbook is managed in the file https://gitlab.com/antora/antora/blob/master/packages/playbook/lib/config/schema.js[schema.js].
The schema defines the hierarchy of configuration properties as well as the names of environment variables and process arguments that can be used to override the default values or the values specified in the playbook spec.
It may be possible in the future for extensions to contribute entries to these schema.
It may be possible in the future for extensions to contribute entries to the schema.
The playbook object (`playbook`) produced by this component should be a well-defined, read-only data model.
This model should allow the playbook properties to be referenced using path navigation (e.g., `playbook.content.sources`).
This model should be easily reproduced by another means, such as an alternate implementation of the playbook component.
This model should be easy to reproduce by another means, such as an alternate implementation of the playbook component.
Each section of configuration (site, content, ui) should be represented by a dedicated model type whose properties (name, location, and type) can be easily converted into API documentation (for example, using a tool like https://github.com/documentationjs/documentation[documentationjs]).
== Consequences
Once the playbook is built, all user input has been captured and the pipeline can proceed to generate the site based on these parameters.
Almost all subsequent components will be configured in some way base on information provided in the playbook.
Almost all subsequent components will be configured in some way based on information provided in the playbook.
No other component should look for user input for the site other than in the playbook.
By introducing a dedicated playbook component to handle user configuration, the configuration step is decoupled from the rest of the pipeline and the runtime environment.
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment