Usage

Preparing your WDL files

Before the documentation can be generated, each input and ouput in your WDL file must be given a description and category. This is done using WDL’s parameter_meta section:

parameter_meta {
    name_of_input: {
        description: "Some description of the input",
        category: "some category"
    }
}

These fields (description and category may also be called differently, but you will have to set some additional options when running WDL-AID, see Custom description and category keys.

WDL-AID will separate the inputs (and outputs) by category, so each category may be rendered in its own section. Required inputs are automatically detected and assigned the required category, overwriting the one noted in the parameter_meta section. This behaviour can be diabled using the --do-not-separate-required flag.

The default template supports the following categories for inputs:

  • required

  • common

  • advanced

  • other

For outputs any set categories will be ignored in the default template. All outputs will instead get listed under one header.

Excluding inputs

In some cases there may be inputs/outputs which should not be included in the documentation, eg. when using a sub-workflow which provides options which make no sense in the context of the overarching workflow. You can tell WDL_AID to omit certain inputs/outputs by adding the following to your workflow’s meta section:

WDL_AID: {
    exclude: ["input_name", "call.input_name"]
}

The inputs added here may be part of the workflow or task containing the meta section or from any call made inside of the workflow. Be sure to use the input names qualified relative to this workflow, ie. input_name for inputs of the task/workflow itself, call_name.input_name for inputs of calls, call_name.sub_call_name.input_name for calls inside of sub-workflows, etc.

Metadata

The meta section of your workflow may also be used to pass additional information along to WDL-AID. The entire meta section of the workflow that WDL-AID gets called on is passed to the template unaltered. WDL-AID will also retrieve all authors from the meta sections of every called task and workflow and pass these along.

The default template supports the following meta section entries:

  • description (only for the root workflow)

  • authors (also for sub-workflows and tasks)

    This is expected to be an object containing the following fields for each author:

    • name

    • email (optional)

    • organization (optional)

    eg.

    meta {
        authors: [
            {
                name: "Eddard Stark",
                email: "StarkNed@winterfell.westeros",
                organization: "The North"
            },{
                name: "Jon Snow",
                email: "j.snow@nightswatch.westeros",
                organization: "The Night's Watch"
            }
        ]
    }
    

Running WDL-AID

WDL-AID can be run with the following command:

wdl-aid <workflow.wdl>

This will print the generated documentation to stdout. This will be markdown formatted text when using the default template.

Writing to a file

To write the output to a file the following option can be used:

-o OUTPUT, --output OUTPUT

The file to write the generated documentation to.

Fallback/default values

If no description or category is defined then WDL-AID will fallback to a default value. By default these values equal ??? and other respectively. You may override these fallback values using the following options:

--fallback-description FALLBACK_DESCRIPTION

The fallback value for when no description is defined for a given input/output.

--fallback-category FALLBACK_CATEGORY

The fallback value for when no category is defined for a given input/output.

In some cases a parameter_meta entry may be defined, but it does not contain the an object with a description item. By default the fallback values will get used in these cases. However, alternatively you can use the entirety of the defined parameter_meta entry as description value using the following flag:

--fallback-description-to-object

Use the entire parameter_meta object as description if the description key is not found.

Custom description and category keys

In case your parameter_meta entries use different keys than description and category to provide the description and category (respectively) of the inputs/outputs, you can use the following options to inform WDL-AID of which keys to look for:

-c CATEGORY_KEY, --category-key CATEGORY_KEY

The key used in the parameter_meta sections for the input/output category.

-d DESCRIPTION_KEY, --description-key DESCRIPTION_KEY

The key used in the parameter_meta section for the input/output description.

Keeping original categories for required inputs

If you wish to retain the categories noted in the parameter_meta sections for the required input, rather then having the overwritten with required then you can use the following flag:

Custom templates

You can provide a custom template using the following option. This template should be a Jinja2 template.

-t TEMPLATE, --template TEMPLATE

A Jinja2 template to use for rendering the documentation.

See Custom templates for more details on making a custom template.

Extra data

It is possible to pass extra data along to the template. This can be done by providing the following option with a json file which contains this extra data.

-e EXTRA, --extra EXTRA

A JSON file with additional data to be passed to the jinja2 rendering engine.

Strict mode

WDL-AID has an option to run in a “strict” mode. This entails that WDL-AID will error if any inputs or outputs are missing a parameter_meta section. This may be useful as part of CI testing, allowing you to ensure that all inputs and outputs will always be documented.

--strict

Error if the parameter_meta entry is missing for any inputs or outputs.

Alternatively, you can use set this strict mode specifically for inputs or outputs as well.

--strict-inputs

Error if the parameter_meta entry is missing for any inputs.

--strict-outputs

Error if the parameter_meta entry is missing for any outputs.