Documentation ideas

[cjfullerton]

I've started this thread so we can collect together ideas for documentation.

The plan is to use the four level system described here: https://diataxis.fr/

When you post an idea, state whether you think it falls under:

• Tutorials
• How-tos
• Explanation
• Reference

Let's restrict this to HPCFlow documentation only. Discussion thread for MatFlow documentation is here: hpcflow/matflow-new#55

[cjfullerton]

Explanation of terms referring to parts of a workflow [Explanation]

An explanation of terms like workflow, schema, task, element, element group, variable, loop pitched at people who will be writing workflow templates.

[aplowman]

How to change the SDK log level [How-tos]

Change the environment variable HPCFLOW_SDK_CONSOLE_LOG_LEVEL to one of the allowed log levels. Mention this is distinct from the app-level log, whose levels can be changed in the config file.

[aplowman]

How to get and set values in the config file from the CLI and from the API [How-tos]

Include examples for getting and setting simple values (e.g. machine) and appending/prepending to container values (e.g. template component files). Also demonstrate how path-like values are resolved.

Show that in the API, values aren't saved to the config file unless the config.save() command is run.

[aplowman]

How to make an hpcflow application [How-tos]

The example being matflow.

[aplowman]

Running a workflow for multiple values of a parameter (i.e. a sequences) [Tutorial]

• defining a sequence in the YAML template and in the API
• choosing appropriate nesting values and the errors if you don't
• accessing sequence information after execution (e.g. which sequence value is this element associated with)

[aplowman]

How and why the SDK is structured as it is [Explanation]

• Based on requirements for a re-usable "App" object, the ability to auto-generate docs from type hints, and straightforward import convention in downstream apps