Update migrate_with_timeouts MC documentation

To include input fields for the retry mechanism.

docs/usage/management_commands.rst

@@ -1,27 +1,70 @@
 Management Commands
 ===================
 
-migrate_with_timeouts
----------------------
+``migrate_with_timeouts``
+-------------------------
 
 Runs database migrations with timeouts.
 
 This command wraps the :ref:`apply_timeouts() <apply_timeouts>` around
-Django's ``migrate`` command, exposing two extra arguments:
+Django's ``migrate`` command, exposing extra arguments to handle retries with
+backoff propagation.
 
-- ``--lock-timeout-in-ms``
-- ``--statement-timeout-in-ms``
++++++++++++++++++++++++
+lock_timeout arguments:
++++++++++++++++++++++++
 
- .. important::
+* ``--lock-timeout-in-ms``: Sets the lock_timeout value for the migration.
+* ``--lock-timeout-max-retries``: How many times to retry after getting a
+  lock_timeout. Defaults to zero, which means no retries.
+* ``--lock-timeout-retry-exp``: The exponential to use for exponential backoff
+  retry if retries are enabled. Defaults to 2.
+* ``--lock-timeout-retry-min-wait-in-ms``: minimum amount of time to wait
+  between lock_timeout retries in milliseconds. Defaults to 3s.
+* ``--lock-timeout-retry-max-wait-in-ms``: Maximum amount of time to wait
+  between lock_timeout retries in milliseconds. Defaults to 10s.
 
-   Both arguments are optional, but at least one must be provided!
+++++++++++++++++++++++++++++
+statement_timeout arguments:
+++++++++++++++++++++++++++++
 
-These arguments will set the value of Postgres' ``lock_timeout`` and
-``statement_timeout`` for the duration of the migration.
+* ``--statement-timeout-in-ms``: Sets statement_timeout for the migration.
+* ``--statement-timeout-max-retries``: How many times to retry after getting a
+  statement_timeout. Defaults to zero, which means no retries.
+* ``--statement-timeout-retry-exp``: The exponential to use for exponential
+  backoff retry if retries are enabled. Defaults to 2.
+* ``--statement-timeout-retry-min-wait-in-ms``: minimum amount of time to wait
+  between statement timeout retries in milliseconds. Defaults to 3s.
+* ``--statement-timeout-retry-max-wait-in-ms``: Maximum amount of time to wait
+  between statement timeout retries in milliseconds. Defaults to 10s.
 
-==========
++++++++++++++++
+retry callback:
++++++++++++++++
+
+* ``--retry-callback--path``: Sets a callback to be called after a timeout
+  event has happened. An example is set below:
+
+  .. code-block:: python
+
+    import logging
+
+    from django_pg_migration_tools import timeouts
+    from django_pg_migration_tools.management.commands import migrate_with_timeouts
+
+
+    def timeout_callback(state: migrate_with_timeouts.RetryState) -> None:
+        if isinstance(state.exc, timeouts.DBLockTimeoutError):
+            logging.info("A lock timeout just happened!")
+        elif isinstance(state.exc, timeouts.DBStatementTimeoutError):
+            logging.info("A statement timeout just happened!")
+
+        logging.info(f"{state.lock_timeouts_count} lock timeouts so far!")
+        logging.info(f"{state.statement_timeouts_count} statement timeouts so far!")
+
+++++++++++
 How to use
-==========
+++++++++++
 
 1. Include ``django_pg_migration_tools`` in your ``INSTALLED_APPS``.
 
@@ -37,4 +80,14 @@ How to use
 
 .. code-block:: bash
 
-  ./manage.py migrate_with_timeouts --lock-timeout-in-ms=10000 --statement-timeout-in-ms=60000
+  ./manage.py migrate_with_timeouts \
+    --lock-timeout-in-ms=10000 \
+    --lock-timeout-max-retries=3 \
+    --lock-timeout-retry-exp=2 \
+    --lock-timeout-retry-min-wait-in-ms=3000 \
+    --lock-timeout-retry-max-wait-in-ms=10000 \
+    --statement-timeout-max-retries=3 \
+    --statement-timeout-retry-exp=2 \
+    --statement-timeout-retry-min-wait-in-ms=3000 \
+    --statement-timeout-retry-max-wait-in-ms=10000 \
+    --retry-callback--path="dotted.path.to.callback.function"