diff --git a/mkdocs.yml b/mkdocs.yml index bd62c384..757dcd2d 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -25,6 +25,7 @@ theme: name: Switch to dark mode - media: "(prefers-color-scheme: dark)" scheme: slate + accent: lime toggle: icon: material/brightness-4 name: Switch to light mode @@ -35,6 +36,7 @@ theme: plugins: - search - awesome-pages + - autorefs - mike - mkdocstrings: handlers: @@ -51,6 +53,13 @@ markdown_extensions: - admonition - pymdownx.snippets: check_paths: true + - pymdownx.highlight: + anchor_linenums: true + line_spans: __span + pygments_lang_class: true + - pymdownx.inlinehilite + - pymdownx.superfences + - pymdownx.details extra: version: diff --git a/pyslurm/core/job/job.pxd b/pyslurm/core/job/job.pxd index 5e8dfd4f..d1c8ddf8 100644 --- a/pyslurm/core/job/job.pxd +++ b/pyslurm/core/job/job.pxd @@ -68,7 +68,7 @@ from pyslurm.slurm cimport ( cdef class Jobs(dict): - """A collection of Job objects. + """A collection of [pyslurm.Job][] objects. Args: jobs (Union[list, dict], optional=None): diff --git a/pyslurm/core/job/job.pyx b/pyslurm/core/job/job.pyx index 7f5beae3..bab6ca28 100644 --- a/pyslurm/core/job/job.pyx +++ b/pyslurm/core/job/job.pyx @@ -167,8 +167,9 @@ cdef class Jobs(dict): This function fills in the "steps" attribute for all Jobs in the collection. - Note: Pending Jobs will be ignored, since they don't have any Steps - yet. + !!! note + + Pending Jobs will be ignored, since they don't have any Steps yet. Raises: RPCError: When retrieving the Job information for all the Steps @@ -241,7 +242,8 @@ cdef class Job: Implements the slurm_load_job RPC. - Note: + !!! note + If the Job is not pending, the related Job steps will also be loaded. @@ -454,8 +456,6 @@ cdef class Job: release the Job again. If you specify the mode as "user", the User will also be able to release the job. - Note: Uses the modify() function to set the Job's priority to 0. - Raises: RPCError: When holding the Job was not successful. @@ -478,9 +478,6 @@ cdef class Job: def release(self): """Release a currently held Job, allowing it to be scheduled again. - Note: Uses the modify() function to reset the priority back to - be controlled by the slurmctld's priority calculation routine. - Raises: RPCError: When releasing a held Job was not successful. @@ -1223,14 +1220,13 @@ cdef class Job: def get_resource_layout_per_node(self): """Retrieve the resource layout of this Job on each node. - The dict returned contains the following information for each node: - * cpu_ids (str) - * gres (dict) - * memory (int) + !!! warning + + Return type may still be subject to change in the future Returns: (dict): Resource layout, where the key is the name of the name and - its value another dict with the components described above. + its value another dict with the CPU-ids, memory and gres. """ # The code for this function is a modified reimplementation from here: # https://github.com/SchedMD/slurm/blob/d525b6872a106d32916b33a8738f12510ec7cf04/src/api/job_info.c#L739 diff --git a/pyslurm/core/job/step.pxd b/pyslurm/core/job/step.pxd index ed61d4d9..087742d6 100644 --- a/pyslurm/core/job/step.pxd +++ b/pyslurm/core/job/step.pxd @@ -50,7 +50,7 @@ from pyslurm.core.job.task_dist cimport TaskDistribution cdef class JobSteps(dict): - """A collection of [`pyslurm.JobStep`][] objects for a given Job. + """A collection of [pyslurm.JobStep][] objects for a given Job. Args: job (Union[Job, int]): diff --git a/pyslurm/core/job/submission.pxd b/pyslurm/core/job/submission.pxd index f9c9d877..1547f5de 100644 --- a/pyslurm/core/job/submission.pxd +++ b/pyslurm/core/job/submission.pxd @@ -312,8 +312,8 @@ cdef class JobSubmitDescription: * "no" or "exclusive" No sharing of resources is allowed. (--exclusive from sbatch) - distribution (Union[dict, str]): - TODO + distribution (str): + Task distribution for the Job, same as --distribution from sbatch time_limit (str): The time limit for the job. This is the same as -t/--time from sbatch. diff --git a/pyslurm/core/job/submission.pyx b/pyslurm/core/job/submission.pyx index f023f035..50613937 100644 --- a/pyslurm/core/job/submission.pyx +++ b/pyslurm/core/job/submission.pyx @@ -105,11 +105,35 @@ cdef class JobSubmitDescription: def load_environment(self, overwrite=False): """Load values of attributes provided through the environment. + !!! note + + Instead of `SBATCH_`, pyslurm uses `PYSLURM_JOBDESC_` as a prefix to + identify environment variables which should be used to set + attributes. + Args: overwrite (bool): If set to True, the value from an option found in the environment will override the current value of the attribute in this instance. Default is False + + Examples: + Lets consider you want to set the name of the Job and its + Account name. Therefore, you will need to have set these two + environment variables: + + ```bash + export PYSLURM_JOBDESC_ACCOUNT="myaccount" + export PYSLURM_JOBDESC_NAME="myjobname" + ``` + + In python, you can do this now: + + >>> import pyslurm + >>> desc = pyslurm.JobSubmitDescription(...other args...) + >>> desc.load_environment() + >>> print(desc.name, desc.account) + myjobname, myaccount """ self._parse_env(overwrite) diff --git a/pyslurm/core/node.pxd b/pyslurm/core/node.pxd index 412a290c..9ddb7000 100644 --- a/pyslurm/core/node.pxd +++ b/pyslurm/core/node.pxd @@ -58,7 +58,7 @@ from pyslurm.utils.uint cimport * cdef class Nodes(dict): - """A collection of Node objects. + """A collection of [pyslurm.Node][] objects. Args: nodes (Union[list, dict, str], optional=None): diff --git a/pyslurm/core/node.pyx b/pyslurm/core/node.pyx index 050f6262..f869b2ab 100644 --- a/pyslurm/core/node.pyx +++ b/pyslurm/core/node.pyx @@ -131,7 +131,9 @@ cdef class Nodes(dict): def reload(self): """Reload the information for nodes in a collection. - Note: Only information for nodes which are already in the collection at + !!! note + + Only information for nodes which are already in the collection at the time of calling this method will be reloaded. Raises: diff --git a/pyslurm/db/job.pxd b/pyslurm/db/job.pxd index 08673682..28ba5423 100644 --- a/pyslurm/db/job.pxd +++ b/pyslurm/db/job.pxd @@ -149,7 +149,7 @@ cdef class JobSearchFilter: cdef class Jobs(dict): - """A collection of [`pyslurm.db.Job`][] objects.""" + """A collection of [pyslurm.db.Job][] objects.""" cdef: SlurmList info Connection db_conn diff --git a/pyslurm/db/stats.pxd b/pyslurm/db/stats.pxd index 682143e6..1ca9c701 100644 --- a/pyslurm/db/stats.pxd +++ b/pyslurm/db/stats.pxd @@ -37,7 +37,8 @@ from pyslurm.utils cimport cstr cdef class JobStatistics: """Statistics for a Slurm Job or Step. - Note: + !!! note + For more information also see the sacct manpage. Attributes: diff --git a/pyslurm/db/step.pxd b/pyslurm/db/step.pxd index d13e3da7..aef7120b 100644 --- a/pyslurm/db/step.pxd +++ b/pyslurm/db/step.pxd @@ -44,7 +44,7 @@ from pyslurm.db.tres cimport TrackableResources, TrackableResource cdef class JobSteps(dict): - """A collection of [`pyslurm.db.JobStep`][] objects""" + """A collection of [pyslurm.db.JobStep][] objects""" pass diff --git a/scripts/builddocs.sh b/scripts/builddocs.sh index cc5625c2..b56482f1 100755 --- a/scripts/builddocs.sh +++ b/scripts/builddocs.sh @@ -1,5 +1,6 @@ #!/bin/bash +python setup.py clean pip install -r doc_requirements.txt pip install --no-build-isolation -e . mkdocs build