Add extra parameter to give human-readable docs for template components

Fixes #704

docs/source/reference/template_components/command_files.rst

@@ -7,5 +7,5 @@ Command files
 
    {{i.label}}
    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-   {{i}}
+   {{i.documentation}}
    {% endfor %}

docs/source/reference/template_components/environments.rst

@@ -7,5 +7,5 @@ Environments
 
    {{i.name}}
    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-   {{i}}
+   {{i.documentation}}
    {% endfor %}

hpcflow/data/template_components/command_files.yaml

@@ -1,19 +1,25 @@
 - label: t1_infile_1
   name:
     name: t1_infile_1.txt
+  doc: Input file for demonstration task t1.
 - label: t1_infile_2
   name:
     name: t1_infile_2.txt
+  doc: Input file for demonstration task t1.
 - label: t1_outfile_1
   name:
     name: outfile.txt
+  doc: Output file for demonstration task t1.
 - label: lammps_atoms_file
   name:
     name: atoms.lammps
+  doc: The file of atoms processed by LAMMPS.
 - label: lammps_input_script
   name:
     name: in.lammps
+  doc: The LAMMPS control file.
 - label: lammps_dump_files
   name:
     name: (dump.\d+.txt)
     is_regex: true
+  doc: A regular expression pattern that matches LAMMPS dump files. (<code>(dump.\d+.txt)</code>)

hpcflow/data/template_components/environments.yaml

@@ -1,4 +1,5 @@
 - name: null_env
+  doc: The default system environment.
 
 - name: python_env
   executables:
@@ -7,3 +8,6 @@
         - command: python <<script_name>> <<args>>
           num_cores: 1
           parallel_mode: null
+  doc: |
+    An environment for running Python, typically with access to hpcflow and matflow modules and their dependencies.
+    May be a Python virtual environment.

hpcflow/data/template_components/parameters.yaml

@@ -1,3 +1,4 @@
+# These are only documented when their schemas are documented.
 - type: p1
 - type: p1c
 - type: p2

hpcflow/data/template_components/task_schemas.yaml

@@ -1,4 +1,7 @@
 - objective: test_t1_bash
+  doc: >
+    Simple echo test using bash.
+    <code>p1</code> &rarr; <code>p2</code>
   inputs:
     - parameter: p1
   outputs:
@@ -13,6 +16,9 @@
           stdout: <<parameter:p2>>
 
 - objective: test_t1_ps
+  doc: >
+    Simple echo test using powershell.
+    <code>p1</code> &rarr; <code>p2</code>
   inputs:
     - parameter: p1
   outputs:
@@ -27,6 +33,9 @@
           stdout: <<parameter:p2>>
 
 - objective: test_t1_conditional_OS
+  doc: >
+    Simple echo test showing conditional enactment schemes.
+    <code>p1</code> &rarr; <code>p2</code>
   inputs:
     - parameter: p1
   outputs:
@@ -54,6 +63,9 @@
           stdout: <<parameter:p2>>
 
 - objective: test_t2_bash
+  doc: >
+    Simple echo test using bash.
+    <code>p2</code> &rarr; <code>p3</code>
   inputs:
     - parameter: p2
   outputs:
@@ -68,6 +80,9 @@
           stdout: <<parameter:p3>>
 
 - objective: test_t2_ps
+  doc: >
+    Simple echo test using powershell.
+    <code>p2</code> &rarr; <code>p3</code>
   inputs:
     - parameter: p2
   outputs:
@@ -100,6 +115,9 @@
 #           from_files: [t1_outfile_1]
 
 - objective: dummy_task_1
+  doc: >
+    A dummy task showing simple output file parsing.
+    <code>(p1, p2, p5)</code> &rarr; <code>p3</code>
   inputs:
     - parameter: p1
     - parameter: p2
@@ -119,6 +137,9 @@
           from_files: [t1_outfile_1]
 
 - objective: dummy_task_2
+  doc: >
+    A dummy task showing simple output file parsing.
+    <code>(p3, orientations)</code> &rarr; <code>p4</code>
   inputs:
     - parameter: p3
     - parameter: orientations

hpcflow/sdk/core/command_files.py

@@ -32,6 +32,8 @@ class FileSpec(JSONLike):
     label: str
     #: The name of the file.
     name: str
+    #: Documentation for the file specification.
+    doc: str = ""
     _hash_value: Optional[str] = field(default=None, repr=False)
 
     def __post_init__(self):
@@ -66,6 +68,15 @@ def ext(self):
         """
         return self.name.ext
 
+    @property
+    def documentation(self) -> str:
+        """
+        Documentation for rendering via Jinja.
+        """
+        if self.doc:
+            return f"File specifier. {self.doc}"
+        return repr(self)
+
 
 class FileNameSpec(JSONLike):
     """

hpcflow/sdk/core/environment.py

@@ -211,10 +211,18 @@ class Environment(JSONLike):
     )
 
     def __init__(
-        self, name, setup=None, specifiers=None, executables=None, _hash_value=None
+        self,
+        name,
+        setup=None,
+        specifiers=None,
+        executables=None,
+        doc="",
+        _hash_value=None,
     ):
         #: The name of the environment.
         self.name = name
+        #: Documentation for the environment.
+        self.doc = doc
         #: Commands to run to enter the environment.
         self.setup = setup
         #: Dictionary of attributes that may be used to supply addional key/value pairs
@@ -257,3 +265,9 @@ def _validate(self):
                 f"Executables must have unique `label`s within each environment, but "
                 f"found label(s) multiple times: {dup_labels!r}"
             )
+
+    @property
+    def documentation(self) -> str:
+        if self.doc:
+            return self.doc
+        return repr(self)

hpcflow/sdk/core/task_schema.py

@@ -112,6 +112,7 @@ def __init__(
         parameter_class_modules: Optional[List[str]] = None,
         web_doc: Optional[bool] = True,
         environment_presets: Optional[Dict[str, Dict[str, Dict[str, Any]]]] = None,
+        doc: str = "",
         _hash_value: Optional[str] = None,
     ):
         #: This is a string representing the objective of the task schema.
@@ -133,6 +134,8 @@ def __init__(
         self.web_doc = web_doc
         #: Information about default execution environments.
         self.environment_presets = environment_presets
+        #: Documentation information about the task schema.
+        self.doc = doc
         self._hash_value = _hash_value
 
         self._set_parent_refs()
@@ -589,11 +592,16 @@ def _prepare_script_data_format_table(script_data_grouped):
             )
             action_show_hide = ""
             act_heading_class = ""
+        description = (
+            f"<h3 class='task-desc'>Description</h3>{self.doc}" if self.doc else "" 
+        )
         out = (
-            f"<h5>Inputs</h5>{inputs_table}"
-            f"<h5>Outputs</h5>{outputs_table}"
-            # f"<h5>Examples</h5>examples here..." # TODO:
-            f"<h5{act_heading_class}>Actions{action_show_hide}</h5>{action_table}"
+            f"{description}"
+            f"<h3>Inputs</h3>{inputs_table}"
+            f"<h3>Outputs</h3>{outputs_table}"
+            # f"<h3>Examples</h3>examples here..." # TODO:
+            f"<h3{act_heading_class}>Actions{action_show_hide}</h3>"
+            f"{action_table}"
         )
         return out