Update documentation to re-include intermediate restarts and restart_…

…history

docs/source/config.rst

@@ -189,25 +189,28 @@ configuration.
             ncpus: 0
 
 ``restart_freq`` (*Default:* ``5``)
-   Specifies the rate of saved restart files. For the default rate of 5, we
-   keep the restart files for every fifth run (``restart004``, ``restart009``,
-   ``restart014``, etc.).
-   Using ``restart_freq: 1`` will save all restart files.
-
-   For both integer and date-based restart frequency, the first restart and,
-   by default, the 5 latest restarts are saved.
+   Specifies the rate of saved restart files. This rate can be either an 
+   integer or date-based. For the default rate of 5, we
+   keep the restart files for every fifth run (``restart000``, ``restart005``,
+   ``restart010``, etc.). To save all restart files, set ``restart_freq: 1``.
+
+   If ``restart_history`` is not configured, intermediate restarts are not 
+   deleted until a permanently archived restart has been produced. 
+   For example, if we have just completed run ``11``, then
+   we keep ``restart000``, ``restart005``, ``restart010``, and ``restart011``.
+   Restarts 11 through 14 are not deleted until ``restart015`` has been saved.
 
    To use a date-based restart frequency, specify a number with a time unit.
    The supported time units are  ``YS`` - year-start, ``MS`` - month-start,
    ``W`` - week, ``D`` - day, ``H`` - hour, ``T`` - minute and ``S`` - second.
    For example, ``restart_freq: 10YS`` would save earliest restart of the year,
-   10 years from the last permanently saved restart's datetime.
+   10 years from the last permanently archived restart's datetime.
 
-   Please note that currently, only ACCESS-OM2 and MOM models support
-   date-based restart frequency, as it depends the payu model driver being
+   Please note that currently, only ACCESS-OM2, MOM5 and MOM6 models support
+   date-based restart frequency, as it depends on the payu model driver being
    able to parse restarts files for a datetime.
 
-``restart_history`` (*Default:* ``5``)
+``restart_history``
     Specifies the number of latest restart files to save
 
 *The following model-based tags are typically not configured*

docs/source/usage.rst

@@ -232,6 +232,12 @@ To run from an existing model run, also called a warm start, set the
 ``restart`` option to point to the folder containing the restart files
 from a previous matching experiment.
 
+If restart pruning configuration has changed, there may be warnings if 
+many restarts will be pruned as a result. If this is desired, at the next 
+run use ``-F/--force-prune-restarts`` flag:
+
+  payu run --force-prune-restarts
+
 
 Cleaning up 
 ===========

test/test_prune_restarts.py

@@ -184,8 +184,14 @@ def test_force_prune_restarts(restart_freq,
             (0, "1901-01-01 00:00:00"),
             (2, "1903-01-01 00:00:00"),
             (3, "1904-01-01 00:00:00"),
-            (4, "1904-01-01 00:00:00"),
-        ], 2, None, [3])
+            (4, "1905-01-01 00:00:00"),
+        ], 2, None, [3]),
+        ([
+            (2, "1903-01-01 00:00:00"),
+            (4, "1905-01-01 00:00:00"),
+            (6, "1907-01-01 00:00:00"),
+            (8, "1909-01-01 00:00:00"),
+        ], 4, None, []),
     ])
 def test_prune_restarts(restarts,
                         restart_freq,