code review

distributed/active_memory_manager.py

@@ -306,7 +306,7 @@ def run(
 
         .. code-block:: python
 
-           choice = yield "replicate", ts, None
+           choice = (yield "replicate", ts, None)
 
         ``choice`` is either a WorkerState or None; the latter is returned if the
         ActiveMemoryManager chose to disregard the request.

docs/source/active_memory_manager.rst

@@ -100,7 +100,9 @@ computation, this policy drops all excess replicas.
 
 .. note::
    This policy is incompatible with :meth:`~distributed.Client.replicate` and with the
-   ``broadcast`` parameter of :meth:`~distributed.Client.scatter`.
+   ``broadcast=True`` parameter of :meth:`~distributed.Client.scatter`. If you invoke
+   ``replicate`` to create additional replicas and then later run this policy, it will
+   delete all replicas but one (but not necessarily the new ones).
 
 
 Custom policies
@@ -142,6 +144,9 @@ define two methods:
     - Create replicas of a task on workers that already hold them
     - Create replicas on paused or retiring workers
 
+    It is generally a good idea to design policies to be as simple as possible and let
+    the AMM take care of the edge cases above by ignoring some of the suggestions.
+
     Optionally, the ``run`` method may retrieve which worker the AMM just selected, as
     follows:
 

docs/source/conf.py

@@ -147,7 +147,7 @@
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = []
+html_static_path: list[str] = []
 
 # Add any extra paths that contain custom files (such as robots.txt or
 # .htaccess) here, relative to this directory. These files are copied