How to document your variables

FAST-OAD can associate a description to each variable. Such description will be put as comment in datafiles, or displayed along with other variable information, like in command line (see How to get list of variables).

The description of a variable can be defined in two ways:

Defining variable description in your OpenMDAO component

OpenMDAO natively allows to define the description of a variable when declaring it.

FAST-OAD will retrieve this information (the description has to be defined once, even if the variable is declared at several locations).

Defining variable description in dedicated files

If you want to add description to your variables in a more centralized way, FAST-OAD will look for files named variable_descriptions.txt that are dedicated to that.

The file content is expected to process one variable per line, containing the variable name and its description, separated by ||, as in following example:

my:variable||The description of my:variable, as long as needed, but on one line.
# Comments are allowed
my:other:variable || Another description (surrounding spaces are ignored)

FAST-OAD will search such files:

• in the root package of plugin modules (see How to add custom OpenMDAO modules to FAST-OAD as a plugin)

• in the root folder of module folders as declared in configuration file (see Modify the configuration file)

• in the same package as any class which is declared as FAST-OAD module (see Register your system(s))

In practice, here you can see what description files will be consider, depending on their location:

my_modules/
├── __init__.py
├── subpackage1
│   ├── __init__.py
│   ├── model.py                      <- contains a class decorated with
│   │                                    RegisterOpenMDAOSystem
│   └── variable_descriptions.txt     <- this file will be loaded
├── subpackage2
│   ├── __init__.py
│   ├── propulsion_model.py           <- contains a class decorated with
│   │                                    RegisterOpenPropulsion
│   └── variable_descriptions.txt     <- this file will be loaded
├── util
│   ├── __init__.py
│   ├── utility_module.py             <- no registering done here
│   └── variable_descriptions.txt     <- this file will NOT be loaded
└── variable_descriptions.txt     <- this file will be loaded because it is in root folder/package