Skip to content

ADR 12: Declarative configuration

Context

Original configuration format was described in ADR 6: Direct processors configuration. It used Python module as a configuration format and contains a mixture of simple configuration variables with complex configuration of processors and writers. Course configuration, however, should be simple to write and read. It should not contain details of it4kt-builder implementation.

The original configuration format expected, that in most cases would be just used default configuration of processors. However, each course may have different structure – different set of pages and folders and also links to other resources that should be displayed in the main menu.

Decision

We decided to use declarative configuration format. YAML is used as a host language as it provides good level of readability for structured data. The configuration contains several dictionaries with configuration of different aspects of the course. It also contains a lists pages, folders and links that defines elements of course content and also main menu of the course. 

course:
  title: Course name
  abbreviation: CN

pages:
  - index.xml
  - path: info.xml
    type: subject-info

folders:
  - path: lectures
    title: Lectures
  - path: labs
    title: Labs
    type: scenario
  - path: assignments
    title: Assignments

links:
  - title: Moodle
    url: https://moodle.fei.tuke.sk

theme:
  name: bootstrap

deploy:
  code: example-course

If advanced customization of the processing is needed, an initialization script init.py could be created. This script is loaded immediately ofter the configuration file was read and before creation of processors. The script can modify rules for processors and do any other customizations.

Status

Accepted. Supersedes ADR 6: Direct processors configuration

Consequences

Configuration format allows changes of the implementation of processros in the future. It also does not require users to understand Python and inner structure of the IT4KT-Builder.

The requirement to explicitly list pages and folders in the configuration makes it more explicit. It removes some “magic” from the tool and simplifies changes of the structure.