some more doc fixes (#287)

* Some more docstring enhancements

* clean before building docs

* enable autorefs and more markdown extensions

Author: tazend

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:

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):

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

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]):

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.

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)
 

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):

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:

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

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:

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
 
 

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