doc: clarity

DrYak · DrYak · commit 7806807f0ab5 · 2025-03-14T10:14:05.000+01:00
- rename flag option for clarity
- make docstring clearer regarding option
- update documentation about option and upcoming version
- adapt tests
diff --git a/docs/snakefiles/rules.rst b/docs/snakefiles/rules.rst
@@ -1822,8 +1822,8 @@ Node-local files
 ~~~~~~~~~~~~~~~~
 
 For performance reasons, it is sometimes useful to write intermediate files on a faster storage, e.g., attached locally on the cluster compute node rather than shared over the network.
-Snakemake (since version 8.31.0) allows files to be marked with ``nodelocal``.
-Files marked this way will automatically be marked as ``temp`` (unless option ``mktemp`` is *False*) and rules creating and consuming them will be automatically :ref:`grouped  <job_grouping>` together so Snakemake will schedule them to the same physical node:
+Snakemake (since version 9.0) allows files to be marked with ``nodelocal``.
+Files marked this way will automatically be marked as ``temp`` (unless option ``flag_temp`` is *False*) and rules creating and consuming them will be automatically :ref:`grouped  <job_grouping>` together so Snakemake will schedule them to the same physical node:
 
 .. code-block:: python
 
diff --git a/src/snakemake/io.py b/src/snakemake/io.py
@@ -1140,18 +1140,19 @@ def temp(value):
     return flag(value, "temp")
 
 
-def nodelocal(value, mktemp=True):
+def nodelocal(value, flag_temp=True):
     """
-    A flag for an input or output file that only lives on the compute node executing the group jobs and not accessible from the main snakemake job.
-    e.g. for what some HPC call "local scratch". By default, file is also flagged as a temp
+    A flag for an intermediate file that only lives on the compute node executing the group jobs and not accessible from the main snakemake job.
+    e.g. for what some HPC call "local scratch". This will cause snakemake to automatically group rules on the same compute note.
+    By default, the file is also flagged as a temp (set flag_temp to False to prevent this default flagging).
     """
     if is_flagged(value, "protected"):
         raise SyntaxError("Node-local may not be protected.")
     if is_flagged(value, "storage_object"):
         raise SyntaxError("Node-local cannot be on storage.")
     # NOTE technically a pipe could be nodelocal (if the FIFO is in /tmp)
     # NOTE a directory can be nodelocal
-    if mktemp:
+    if flag_temp:
         value = temp(value)
     return flag(value, "nodelocal")
 
diff --git a/tests/test_nodelocal/Snakefile b/tests/test_nodelocal/Snakefile
@@ -15,7 +15,7 @@ rule create_nodelocal_temp:
 
 rule create_nodelocal_persist:
     output:
-        nodelocal("scratch/persist.txt", mktemp=False),
+        nodelocal("scratch/persist.txt", flag_temp=False),
     shell:
         """
         sleep 4
