Documented custom attributes a bit better

Author: hategan

.gitignore

@@ -17,3 +17,5 @@ psi_j_python.egg-info/
 venv*
 .venv*
 build/
+docs/.web-build
+web-build/

src/psij/executors/batch/cobalt.py

@@ -36,6 +36,10 @@ class CobaltJobExecutor(BatchSchedulerExecutor):
     monitor, and cancel jobs.
 
     Creates a batch script with #COBALT directives when submitting a job.
+
+    Custom attributes prefixed with `cobalt.` are rendered as long-form directives in the script.
+    For example, setting `custom_attributes['cobalt.m'] = 'co'` results in the `#COBALT --m=co`
+    directive being placed in the submit script.
     """
 
     # see https://Cobalt.schedmd.com/squeue.html

src/psij/executors/batch/lsf.py

@@ -35,6 +35,11 @@ class LsfJobExecutor(BatchSchedulerExecutor):
     monitor, and cancel jobs.
 
     Creates a batch script with #BSUB directives when submitting a job.
+
+    Renders all custom attributes of the form `lsf.<name>` into the corresponding
+    LSF directive. For example, setting
+    `job.spec.attributes.custom_attributes['lsf.core_isolation'] = '0' results in a
+    `#BSUB -core_isolation 0` directive being placed in the submit script.
     """
 
     # see https://www.ibm.com/docs/en/spectrum-lsf/10.1.0?topic=bjobs-description

src/psij/executors/batch/pbs_base.py

@@ -58,6 +58,10 @@ class GenericPBSJobExecutor(BatchSchedulerExecutor):
     monitor, and cancel jobs.
 
     Creates a batch script with #PBS directives when submitting a job.
+
+    Custom attributes prefixed with `pbs.` are rendered as directives in the script.
+    For example, setting `custom_attributes['pbs.c'] = 'n'` results in the `#PBS -c n`
+    directive being placed in the submit script, which disables checkpointing.
     """
 
     def __init__(self, generator: TemplatedScriptGenerator, url: Optional[str] = None,

src/psij/executors/batch/slurm.py

@@ -28,6 +28,11 @@ class SlurmJobExecutor(BatchSchedulerExecutor):
     monitor, and cancel jobs.
 
     Creates a batch script with #SBATCH directives when submitting a job.
+
+    Renders all custom attributes set on a job's attributes with a `slurm.` prefix into
+    corresponding Slurm directives with long-form parameters. For example,
+    `job.spec.attributes.custom_attributes['slurm.qos'] = 'debug'` causes a directive
+    `#SBATCH --qos=debug` to be placed in the submit script.
     """
 
     # see https://slurm.schedmd.com/squeue.html

src/psij/job_attributes.py

@@ -31,6 +31,14 @@ def __init__(self, duration: timedelta = timedelta(minutes=10),
         :param custom_attributes: Specifies a dictionary of custom attributes. Implementations of
             :class:`~psij.JobExecutor` define and are responsible for interpreting custom
             attributes.
+            The typical usage scenario for custom attributes is to pass information to the executor
+            or underlying job execution mechanism that cannot otherwise be passed using the classes
+            and properties provided by PSI/J. A specific example is that of the subclasses of
+            :class:`~psij.executors.batch.batch_scheduler_executor.BatchSchedulerExecutor`, which
+            look for custom attributes prefixed with their name and a dot (e.g., `slurm.constraint`,
+            `pbs.c`, `lsf.core_isolation`) and translate them into the corresponding batch
+            scheduler directives (e.g., `#SLURM --constraint=...`, `#PBS -c ...`,
+            `#BSUB -core_isolation ...`).
 
         All constructor parameters are accessible as properties.
         """