Factor out files_to_* documentation.

christinaholtNOAA · christinaholtNOAA · commit ad96f4c921d7 · 2025-09-10T20:29:11.000Z
diff --git a/docs/sections/user_guide/yaml/components/fv3.rst b/docs/sections/user_guide/yaml/components/fv3.rst
@@ -35,15 +35,7 @@ field_table:
 
 The path to a :weather-model-io:`valid field-table file<field-table-file>` to be copied into the run directory.
 
-files_to_copy:
-^^^^^^^^^^^^^^
-
-See :ref:`this page <files_yaml>` for details.
-
-files_to_link:
-^^^^^^^^^^^^^^
-
-Identical to ``files_to_copy:`` except that symbolic links will be created in the run directory instead of copies.
+.. include:: /shared/stager.rst
 
 lateral_boundary_conditions:
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
diff --git a/docs/sections/user_guide/yaml/components/ioda.rst b/docs/sections/user_guide/yaml/components/ioda.rst
@@ -25,15 +25,7 @@ configuration_file:
 
 Supports ``base_file:`` and ``update_values:`` blocks (see :ref:`updating_values` for details).
 
-files_to_copy:
-^^^^^^^^^^^^^^
-
-See :ref:`this page <files_yaml>` for details.
-
-files_to_link:
-^^^^^^^^^^^^^^
-
-Identical to ``files_to_copy:`` except that symbolic links will be created in the run directory instead of copies.
+.. include:: /shared/stager.rst
 
 rundir:
 ^^^^^^^
diff --git a/docs/sections/user_guide/yaml/components/jedi.rst b/docs/sections/user_guide/yaml/components/jedi.rst
@@ -25,15 +25,7 @@ configuration_file:
 
 Supports ``base_file:`` and ``update_values:`` blocks (see :ref:`updating_values` for details).
 
-files_to_copy:
-^^^^^^^^^^^^^^
-
-See :ref:`this page <files_yaml>` for details.
-
-files_to_link:
-^^^^^^^^^^^^^^
-
-Identical to ``files_to_copy:`` except that symbolic links will be created in the run directory instead of copies.
+.. include:: /shared/stager.rst
 
 rundir:
 ^^^^^^^
diff --git a/docs/sections/user_guide/yaml/components/mpas.rst b/docs/sections/user_guide/yaml/components/mpas.rst
@@ -49,12 +49,9 @@ length:
 
 The length of the forecast in integer hours.
 
-files_to_copy:
-^^^^^^^^^^^^^^
+.. include:: /shared/stager.rst
 
-See :ref:`this page <files_yaml>` for details.
-
-To reduce duplication of information in this section, it may be helpful to template the file that depends on the number of cores being used to run the executable. For example, instead of:
+To reduce duplication of information in these sections, it may be helpful to template the file that depends on the number of cores being used to run the executable. For example, instead of:
 
 .. code-block:: text
 
@@ -70,11 +67,6 @@ Jinja2 expressions can be used to reference the number of cores used in executio
      files_to_copy:
        conus.graph.info.part.{{mpas.execution["batchargs"]["cores"]}}: /path/to/conus.graph.info.part.{{mpas.execution["batchargs"]["cores"]}}
 
-files_to_link:
-^^^^^^^^^^^^^^
-
-Identical to ``files_to_copy:`` except that symbolic links will be created in the run directory instead of copies.
-
 namelist:
 ^^^^^^^^^
 
diff --git a/docs/sections/user_guide/yaml/components/mpas_init.rst b/docs/sections/user_guide/yaml/components/mpas_init.rst
@@ -43,12 +43,9 @@ execution:
 
 See :ref:`this page <execution_yaml>` for details.
 
-files_to_copy:
-^^^^^^^^^^^^^^
+.. include:: /shared/stager.rst
 
-See :ref:`this page <files_yaml>` for details.
-
-To reduce duplication of information in this section, it may be helpful to template the file that depends on the number of cores being used to run the executable. For example, instead of:
+To reduce duplication of information in these sections, it may be helpful to template the file that depends on the number of cores being used to run the executable. For example, instead of:
 
 .. code-block:: text
 
@@ -64,11 +61,6 @@ Jinja2 expressions can be used to reference the number of cores used in executio
      files_to_copy:
        conus.graph.info.part.{{mpas_init.execution["batchargs"]["cores"]}}: /path/to/conus.graph.info.part.{{mpas_init.execution["batchargs"]["cores"]}}
 
-files_to_link:
-^^^^^^^^^^^^^^
-
-Identical to ``files_to_copy:`` except that symbolic links will be created in the run directory instead of copies.
-
 namelist:
 ^^^^^^^^^
 
diff --git a/docs/sections/user_guide/yaml/components/mpassit.rst b/docs/sections/user_guide/yaml/components/mpassit.rst
@@ -21,12 +21,9 @@ execution:
 
 See :ref:`this page <execution_yaml>` for details.
 
-files_to_copy:
-^^^^^^^^^^^^^^
+.. include:: /shared/stager.rst
 
-See :ref:`this page <files_yaml>` for details.
-
-To reduce duplication of information in this section, it may be helpful to reference the config value that specifies the number of cores used to run the executable. For example, instead of:
+To reduce duplication of information in these sections, it may be helpful to reference the config value that specifies the number of cores used to run the executable. For example, instead of:
 
 .. code-block:: text
 
@@ -42,11 +39,6 @@ Jinja2 expressions can be used to reference the number of cores used for executi
      files_to_copy:
        x1.999.graph.info.part.{{ mpassit.execution.batchargs.cores }}: /path/to/x1.999.graph.info.part.{{ mpassit.execution.batchargs.cores }}
 
-files_to_link:
-^^^^^^^^^^^^^^
-
-Identical to ``files_to_copy:`` except that symbolic links will be created in the run directory instead of copies.
-
 namelist:
 ^^^^^^^^^
 
diff --git a/docs/sections/user_guide/yaml/components/orog.rst b/docs/sections/user_guide/yaml/components/orog.rst
@@ -26,15 +26,7 @@ execution:
 
 See :ref:`here <execution_yaml>` for details.
 
-files_to_copy:
-^^^^^^^^^^^^^^
-
-See :ref:`this page <files_yaml>` for details.
-
-files_to_link:
-^^^^^^^^^^^^^^
-
-Identical to ``files_to_copy:`` except that symbolic links will be created in the run directory instead of copies.
+.. include:: /shared/stager.rst
 
 mask:
 ^^^^^
diff --git a/docs/sections/user_guide/yaml/components/upp.rst b/docs/sections/user_guide/yaml/components/upp.rst
@@ -21,15 +21,7 @@ execution:
 
 See :ref:`this page <execution_yaml>` for details.
 
-files_to_copy:
-^^^^^^^^^^^^^^
-
-See :ref:`this page <files_yaml>` for details.
-
-files_to_link:
-^^^^^^^^^^^^^^
-
-Identical to ``files_to_copy:`` except that symbolic links will be created in the run directory instead of copies.
+.. include:: /shared/stager.rst
 
 namelist:
 ^^^^^^^^^
diff --git a/docs/sections/user_guide/yaml/components/upp_assets.rst b/docs/sections/user_guide/yaml/components/upp_assets.rst
@@ -16,15 +16,7 @@ Here is a prototype UW YAML ``upp_assets:`` block, explained in detail below:
 UW YAML for the ``upp_assets:`` Block
 -------------------------------------
 
-files_to_copy:
-^^^^^^^^^^^^^^
-
-See :ref:`this page <files_yaml>` for details.
-
-files_to_link:
-^^^^^^^^^^^^^^
-
-Identical to ``files_to_copy:`` except that symbolic links will be created in the run directory instead of copies.
+.. include:: /shared/stager.rst
 
 namelist:
 ^^^^^^^^^
diff --git a/docs/shared/stager.rst b/docs/shared/stager.rst
@@ -0,0 +1,17 @@
+
+.. _filestager_yaml:
+
+files_to_copy:
+^^^^^^^^^^^^^^
+
+See :ref:`this page <files_yaml>` for details.
+
+files_to_hardlink:
+^^^^^^^^^^^^^^
+
+Identical to ``files_to_copy:`` except that hard links will be created in the run directory instead of copies, when possible. Otherwise a copy will be created.
+
+files_to_link:
+^^^^^^^^^^^^^^
+
+Identical to ``files_to_copy:`` except that symbolic links will be created in the run directory instead of copies.
