documentation

nb_slurm/kernelmanager.py

@@ -97,6 +97,17 @@ class SlurmKernelManager(IOLoopKernelManager):
         self.slurm_jobid = None
 
     def start_kernel(self, **kw):
+        """Starts a kernel on a remote host, using 'salloc' and 'srun' to
+        allocate an interactive shell on a remote node and launching a kernel
+        there with 'exec'.
+
+        Parameters
+        ----------
+        `**kw` : optional
+             keyword arguments that are passed down to build the kernel_cmd
+             and launching the kernel. Only 'env' and 'extra_arguments' have
+             an impact, but others are stored to be on the safe side.
+        """
         # Prepare the environment for kernel
         env = kw.pop('env', os.environ).copy()
         # Don't allow PYTHONEXECUTABLE to be passed to kernel process.
@@ -149,7 +160,7 @@ class SlurmKernelManager(IOLoopKernelManager):
             In all cases the kernel is restarted, the only difference is whether
             it is given a chance to perform a clean shutdown or not.
 
-        newports : igored
+        newports : ingored, always True effectively
             Left for the compatibility with Jupyter's reference
             implementation. We can't guarantee, that node of the new kernel
             will be the same, so ports are always cleaned and assigned freshly.
@@ -171,6 +182,15 @@ class SlurmKernelManager(IOLoopKernelManager):
             self.start_kernel(**self._launch_args)
 
     def _launch_slurm_shell(self, env):
+        """Launches an interactive SLURM shell with 'salloc' and 'srun' and
+        returns information about it.
+
+        Parameters
+        ----------
+        `env` : dict or None
+            A dictionary of environment variables, passed to the process. If
+            None, shell inherits parent process' environment.
+        """
         metadata = self.kernel_spec.metadata.get(self._metadata_namespace, None)
         if metadata is None:
             raise SlurmAllocationError("SLURM metadata for the kernel"
@@ -213,6 +233,9 @@ class SlurmKernelManager(IOLoopKernelManager):
             raise_from(SlurmAllocationError(e), tb)
 
     def write_connection_file(self):
+        """Write connection info to JSON dict and assign
+        self.connection_file.
+        """
         if (self._connection_file_written and
                 os.path.exists(self.connection_file)):
             return
@@ -286,6 +309,7 @@ class SlurmKernelManager(IOLoopKernelManager):
             return True
 
     def _kill_kernel(self):
+        """Kill the running kernel."""
         if self.has_kernel:
             self.kernel.kill(1)
             self.kernel.wait()
@@ -295,13 +319,14 @@ class SlurmKernelManager(IOLoopKernelManager):
             raise RuntimeError("Cannot kill kernel. No kernel is running!")
 
     def signal_kernel(self, signum):
+        """Sends a signal to the shell, where the kernel is being executed."""
         if self.has_kernel:
             self.kernel.kill(signum)
         else:
             raise RuntimeError("Cannot signal kernel. No kernel is running!")
 
     def is_alive(self):
-        """Kernel is treated as alive, if its job exists and its state is
+        """Kernel is considered as alive, if its job exists and its state is
         RUNNING
         """
         out = PopenSpawn([self.scontrol_command,

nb_slurm/kernelspecmanager.py

@@ -11,6 +11,12 @@ except ImportError:
 
 # noinspection PyClassHasNoInit
 class SlurmKernelSpecManager(KernelSpecManager):
+    """For each Jupyter kernel profile its parent finds this class generates
+    a set of child profiles, that are used to execute these kernels with
+    different SLURM parameters. Parameters are configurable via Jupyter
+    config and passed to the Kernel Manager via KernelSpec metadata.
+     """
+
     profiles = Dict(
         default_value={'default': []},
         help=(
@@ -32,6 +38,10 @@ class SlurmKernelSpecManager(KernelSpecManager):
     metadata_salloc_args = 'salloc_args'
 
     def find_kernel_specs(self):
+        """Gets kernel spec from `nb_conda_kernels.CondaKernelSpecManager` or
+        `jupyter_client.kernelspec.KernelSpecManager` and generates SLURM
+        profiles for each of them.
+        """
         kspecs = super(SlurmKernelSpecManager, self).find_kernel_specs()
         return {
             self._kn_separator.join((kernel_name, profile_name)): profile_loc
@@ -40,6 +50,10 @@ class SlurmKernelSpecManager(KernelSpecManager):
         }
 
     def get_kernel_spec(self, kernel_name):
+        """Returns a :class:`KernelSpec` instance for the given kernel_name.
+
+        Raises KeyError if the given kernel name is not found.
+        """
         splitted = kernel_name.split(self._kn_separator)
         orig_name = self._kn_separator.join(splitted[:-1])
         profile_name = splitted[-1]