Config

Configuration used across Moa objects within CPL experiments.

Overview

Configuration works as follows. Each class that has configuration attributes must list these attributes in a list in the class __settings_attrs__ attribute. Each of the properties listed there must be Kivy properties of that class.

When generating docs, the documentation of these properties are dumped to a json file using create_doc_listener() (and should be committed to the repo manually).

Each experiment defines a application class based on ExperimentApp. Using this classe’s get_config_classes() method we get a list of all classes used in the current experiment that requires configuration and write_config_attrs_rst() is used to combine all these docs and display them in a single place in the generated html pages.

Similarly, when the app is run, a single json file is generated with all these config values and is later read and is used to configure the experiment by the user. app_settings is where it’s stored after reading. Each class is responsible for reading its configuration from there.

Usage

When creating an experiment, ensure that the root stage called RootStage inherited from ConfigStageBase overwrites the get_config_classes() method returning all the classes that need configuration.

Then, in the sphinx conf.py file do:

def setup(app):
    create_doc_listener(app, project_name)
    app.connect('build-finished', partial(write_config_attrs_rst, ProjectApp.get_config_classes(), project_name))

and run make html twice. This will create the config_attrs.json file under project_name/data and the config.rst file under doc/source. This config.rst should have been listed in the sphinx index so on the second run this file will be converted to html containing all the config tokens.

The config_attrs.json files are read for all the projects on which the experiment depends on, so they should exist in the repos.

cplcom.config.populate_config(filename, classes, from_file=True)

Reads the config file and loads all the config data for the classes listed in classes.

cplcom.config.apply_config(opts, classes)

Takes the config data read with populate_config() and applys them to any existing class instances listed in classes.

cplcom.config.create_doc_listener(sphinx_app, package, directory='data', filename='config_attrs.json')

Creates a listener for the __settings_attrs__ attributes and dumps their docs to directory/filename for package.

To us, in the sphinx conf.py file do:

def setup(app):
    create_doc_listener(app, package)

where package is the module for which the docs are generated.

After docs generation the generated directory/filename must be committed manually to the repo.

cplcom.config.get_config_attrs_doc(classes, json_map={}, json_default='data\\config_attrs.json')

Objects is a dict of object (class) paths and keys are the names of the config attributes of the class.

cplcom.config.write_config_attrs_rst(classes, package, app, exception, json_map={}, json_default='data\\config_attrs.json', rst_fname='doc\\source\\config.rst')

Walks through all the configurable classes of this experiment (should be gotten from get_config_classes()) and loads the docs of those properties and generates a rst output file with all the tokens.

For example in the sphinx conf.py file do:

def setup(app):
    app.connect('build-finished', partial(write_config_attrs_rst, ProjectApp.get_config_classes(), project_name))

where project_name is the project module and ProjectApp is the App that runs the experiment.