DOC: replace only first partagraph of rng documentation

Author: mdhaber

scipy/_lib/_util.py

@@ -342,10 +342,11 @@ def _transition_to_rng(old_name, *, position_num=None, end_version=None,
         Whether the decorator should replace the documentation for parameter `rng` with
         `_rng_desc` (defined above), which documents both new `rng` keyword behavior
         and typical legacy `random_state`/`seed` behavior. If True, manually replace
-        the function's old `random_state`/`seed` documentation with the desired *final*
-        `rng` documentation; this way, no changes to documentation are needed when the
-        decorator is removed. Use False if the function's old `random_state`/`seed`
-        behavior does not match that described by `_rng_desc`.
+        the first paragraph of the function's old `random_state`/`seed` documentation
+        with the desired *final* `rng` documentation; this way, no changes to
+        documentation are needed when the decorator is removed. Documentation of `rng`
+        after the first blank line is preserved. Use False if the function's old
+        `random_state`/`seed` behavior does not match that described by `_rng_desc`.
 
     """
     NEW_NAME = "rng"
@@ -446,10 +447,13 @@ def wrapper(*args, **kwargs):
             if 'rng' in parameter_names:
                 _type = "{None, int, `numpy.random.Generator`}, optional"
                 _desc = _rng_desc.replace("{old_name}", old_name)
-                _rng_parameter_doc = Parameter('rng', _type, [_desc])
+                old_doc = doc['Parameters'][parameter_names.index('rng')].desc
+                old_doc_keep = old_doc[old_doc.index("") + 1:] if "" in old_doc else []
+                new_doc = [_desc] + old_doc_keep
+                _rng_parameter_doc = Parameter('rng', _type, new_doc)
                 doc['Parameters'][parameter_names.index('rng')] = _rng_parameter_doc
-            doc = str(doc).split("\n", 1)[1]  # remove signature
-            wrapper.__doc__ = str(doc)
+                doc = str(doc).split("\n", 1)[1]  # remove signature
+                wrapper.__doc__ = str(doc)
         return wrapper
 
     return decorator