Right now, we can attach human-readable documentation to parameters in our template components, but we can't do the same for command files, environments or task schemas. We ought to do that!
In particular, we currently render command files and environments in the documentation solely as:
That provides absolutely no guidance at all to users what they might be or if they're relevant. I think this is more critical for the environments, as they also provide guidance to system administrators trying to set up matflow to work in a new cluster, and I've never met a sysadmin who wanted to read the documentation deeply. 😆
For task schemas, the human-readable documentation would be very useful too; it would help me describe to the user why they might use that particular template component, augmenting the current automatically-derived documentation of what the parameters to the component are.
In short, this is an area where we should do better than we do right now.
I believe that adding an additional (optional string) attribute, perhaps called doc, to the three relevant classes and updating the Jinja templates to make use of the attribute would be sufficient.
Right now, we can attach human-readable documentation to parameters in our template components, but we can't do the same for command files, environments or task schemas. We ought to do that!
In particular, we currently render command files and environments in the documentation solely as:
That provides absolutely no guidance at all to users what they might be or if they're relevant. I think this is more critical for the environments, as they also provide guidance to system administrators trying to set up matflow to work in a new cluster, and I've never met a sysadmin who wanted to read the documentation deeply. 😆
For task schemas, the human-readable documentation would be very useful too; it would help me describe to the user why they might use that particular template component, augmenting the current automatically-derived documentation of what the parameters to the component are.
In short, this is an area where we should do better than we do right now.
I believe that adding an additional (optional string) attribute, perhaps called
doc, to the three relevant classes and updating the Jinja templates to make use of the attribute would be sufficient.