docs: def run_scheduler_jobs(
      scheduler: str,
      jobs: Iterator[Job],
      directory: PathLike = Path.cwd(),
      basename: str = "experi",
      dry_run: bool = False,
  ) -> None:
      """Submit a series of commands to a batch scheduler.
  
      This takes a list of strings which are the contents of the pbs files, writes the
      files to disk and submits the job to the scheduler. Files which match the pattern of
      the resulting files <basename>_<index>.pbs are deleted before writing the new files.
  
      To ensure that commands run consecutively the aditional requirement to the run
      script `-W depend=afterok:<prev_jobid>` is added. This allows for all the components
      of the experiment to be conducted in a single script.
  
      Note: Having this function submit jobs requires that the command `qsub` exists,
      implying that a job scheduler is installed.
  
      """
      submit_job = True
      logger.debug("Creating commands in %s files.", scheduler)
  
      # Check scheduler submit command exists
      if scheduler == "pbs":
          submit_executable = "qsub"
      elif scheduler == "slurm":
          submit_executable = "sbatch"
      else:
          raise ValueError("scheduler can only take values ['pbs', 'slurm']")
  
      if shutil.which(submit_executable) is None:
          logger.warning(
              "The `%s` command is not found."
              "Skipping job submission and just generating files",
              submit_executable,
          )
          submit_job = False
  
      # Ensure directory is a Path
      directory = Path(directory)
  
      # remove existing files
      for fname in directory.glob(basename + f"*.{scheduler}"):
          print("Removing {}".format(fname))
          os.remove(str(fname))
  
      # Write new files and generate commands
      prev_jobids: List[str] = []
      for index, job in enumerate(jobs):
          # Generate scheduler file
          content = create_scheduler_file(scheduler, job)
          logger.debug("File contents:\n%s", content)
          # Write file to disk
          fname = Path(directory / "{}_{:02d}.{}".format(basename, index, scheduler))
          with fname.open("w") as dst:
              dst.write(content)
  
          if submit_job or dry_run:
              # Construct command
              submit_cmd = [submit_executable]
  
              if prev_jobids:
                  # Continue to append all previous jobs to submit_cmd so subsequent jobs die along
                  # with the first.
                  afterok = f"afterok:{':'.join(prev_jobids)}"
                  if scheduler == "pbs":
                      submit_cmd += ["-W", f"depend={afterok}"]
                  elif scheduler == "slurm":
                      submit_cmd += ["--dependency", afterok]
  
              # actually run the command
              logger.info(str(submit_cmd))
              try:
                  if dry_run:
                      print(f"{submit_cmd} {fname.name}")
                      prev_jobids.append("dry_run")
                  else:
                      cmd_res = subprocess.check_output(
                          submit_cmd + [fname.name], cwd=str(directory)
                      )
                      prev_jobids.append(cmd_res.decode().strip())
              except subprocess.CalledProcessError:
                  logger.error("Submitting job to the queue failed.")
                  break