Repository: numpy/numpy

Issue:
DOC, TST: matmul docstring fails refguide
The matmul docstring in `numpy/core/code_generators/ufunc_docstrings.py` fails the refguide check in #12253 for a variety of reasons varying from behavior changes to not even closing brackets in `np.array()` declarations.

While I've cleaned up some of the trivial issues, I'm going to mark the rest of the issues in that docstring with the `SKIP` directive and I suggest that they be fixed **after** that PR is merged so that the fixes are properly verified in CI.

I'll probably continue with this approach moving forward until the doctest PR is merged -- adding SKIPs and opening bookmark issues--otherwise I end up as the "human refguide checker" for doc changes.


Discussion:
This diff will fix the issue. It builds on #12253, so it will be easier to make a PR once that lands.
<details>

```
--- a/numpy/core/code_generators/ufunc_docstrings.py
+++ b/numpy/core/code_generators/ufunc_docstrings.py
@@ -2603,13 +2603,13 @@ add_newdoc('numpy.core.umath', 'matmul',
     - Stacks of matrices are broadcast together as if the matrices
       were elements, respecting the signature ``(n,k),(k,m)->(n,m)``:
 
-      >>> a = a = np.full([9,5,7,3], True, dtype=bool)
-      >>> c = np.full([9, 5, 4,3], True, dtype=bool)
-      >>> np.dot(a, c).shape # doctest: +SKIP
-      (9, 5, 7, 9, 5, 4)
-      >>> np.matmul(a, c).shape # doctest: +SKIP
-      (9, 5, 7, 4)
-      >>> # n is 5, k is 3, m is 4
+      >>> a = np.ones([9, 5, 7, 4])
+      >>> c = np.ones([9, 5, 4, 3])
+      >>> np.dot(a, c).shape
+      (9, 5, 7, 9, 5, 3)
+      >>> np.matmul(a, c).shape
+      (9, 5, 7, 3)
+      >>> # n is 7, k is 4, m is 3
 
     The matmul function implements the semantics of the `@` operator introduced

```

Resolving patch:
diff --git a/numpy/core/code_generators/ufunc_docstrings.py b/numpy/core/code_generators/ufunc_docstrings.py
--- a/numpy/core/code_generators/ufunc_docstrings.py
+++ b/numpy/core/code_generators/ufunc_docstrings.py
@@ -846,7 +846,7 @@ def add_newdoc(place, name, doc):
     >>> np.cos(np.zeros((3,3)),np.zeros((2,2)))
     Traceback (most recent call last):
       File "<stdin>", line 1, in <module>
-    ValueError: invalid return array shape
+    ValueError: operands could not be broadcast together with shapes (3,3) (2,2)
 
     """)
 
@@ -2603,13 +2603,13 @@ def add_newdoc(place, name, doc):
     - Stacks of matrices are broadcast together as if the matrices
       were elements, respecting the signature ``(n,k),(k,m)->(n,m)``:
 
-      >>> a = a = np.full([9,5,7,3], True, dtype=bool)
-      >>> c = np.full([9, 5, 4,3], True, dtype=bool)
-      >>> np.dot(a, c).shape # doctest: +SKIP
-      (9, 5, 7, 9, 5, 4)
-      >>> np.matmul(a, c).shape # doctest: +SKIP
-      (9, 5, 7, 4)
-      >>> # n is 5, k is 3, m is 4
+      >>> a = np.ones([9, 5, 7, 4])
+      >>> c = np.ones([9, 5, 4, 3])
+      >>> np.dot(a, c).shape
+      (9, 5, 7, 9, 5, 3)
+      >>> np.matmul(a, c).shape
+      (9, 5, 7, 3)
+      >>> # n is 7, k is 4, m is 3
 
     The matmul function implements the semantics of the `@` operator introduced
     in Python 3.5 following PEP465.
@@ -3484,7 +3484,7 @@ def add_newdoc(place, name, doc):
     >>> np.sinh(np.zeros((3,3)),np.zeros((2,2)))
     Traceback (most recent call last):
       File "<stdin>", line 1, in <module>
-    ValueError: invalid return array shape
+    ValueError: operands could not be broadcast together with shapes (3,3) (2,2)
 
     """)
 
@@ -3670,7 +3670,7 @@ def add_newdoc(place, name, doc):
     >>> np.cos(np.zeros((3,3)),np.zeros((2,2)))
     Traceback (most recent call last):
       File "<stdin>", line 1, in <module>
-    ValueError: invalid return array shape
+    ValueError: operands could not be broadcast together with shapes (3,3) (2,2)
 
     """)
 
@@ -3722,7 +3722,7 @@ def add_newdoc(place, name, doc):
     >>> np.tanh(np.zeros((3,3)),np.zeros((2,2)))
     Traceback (most recent call last):
       File "<stdin>", line 1, in <module>
-    ValueError: invalid return array shape
+    ValueError: operands could not be broadcast together with shapes (3,3) (2,2)
 
     """)
 


Test patch: