Doc: Migrate Numpy ufunc to pure python (#5281)

7 files changed, 81 insertions, 23 deletions

diff --git a/docs/examples/userguide/numpy_ufuncs/ufunc.py b/docs/examples/userguide/numpy_ufuncs/ufunc.py
new file mode 100644
index 000000000..adbb49e8d
--- /dev/null
+++ b/docs/examples/userguide/numpy_ufuncs/ufunc.py
@@ -0,0 +1,8 @@
+# tag: numpy
+import cython
+
+@cython.cfunc
+@cython.ufunc
+def add_one(x: cython.double) -> cython.double:
+    # of course, this simple operation can already by done efficiently in Numpy!
+    return x+1
diff --git a/docs/examples/userguide/numpy_ufuncs/ufunc.pyx b/docs/examples/userguide/numpy_ufuncs/ufunc.pyx
new file mode 100644
index 000000000..b29c071e1
--- /dev/null
+++ b/docs/examples/userguide/numpy_ufuncs/ufunc.pyx
@@ -0,0 +1,8 @@
+# tag: numpy
+cimport cython
+
+
+@cython.ufunc
+cdef double add_one(double x):
+    # of course, this simple operation can already by done efficiently in Numpy!
+    return x+1
diff --git a/docs/examples/userguide/numpy_ufuncs/ufunc_ctuple.py b/docs/examples/userguide/numpy_ufuncs/ufunc_ctuple.py
new file mode 100644
index 000000000..75093d6a9
--- /dev/null
+++ b/docs/examples/userguide/numpy_ufuncs/ufunc_ctuple.py
@@ -0,0 +1,7 @@
+# tag: numpy
+import cython
+
+@cython.cfunc
+@cython.ufunc
+def add_one_add_two(x: cython.int) -> (cython.int, cython.int):
+    return x+1, x+2
diff --git a/docs/examples/userguide/numpy_ufuncs/ufunc_ctuple.pyx b/docs/examples/userguide/numpy_ufuncs/ufunc_ctuple.pyx
new file mode 100644
index 000000000..61127261c
--- /dev/null
+++ b/docs/examples/userguide/numpy_ufuncs/ufunc_ctuple.pyx
@@ -0,0 +1,7 @@
+# tag: numpy
+cimport cython
+
+
+@cython.ufunc
+cdef (int, int) add_one_add_two(int x):
+    return x+1, x+2
diff --git a/docs/examples/userguide/numpy_ufuncs/ufunc_fused.py b/docs/examples/userguide/numpy_ufuncs/ufunc_fused.py
new file mode 100644
index 000000000..dd01a508e
--- /dev/null
+++ b/docs/examples/userguide/numpy_ufuncs/ufunc_fused.py
@@ -0,0 +1,7 @@
+# tag: numpy
+import cython
+
+@cython.cfunc
+@cython.ufunc
+def generic_add_one(x: cython.numeric) -> cython.numeric:
+    return x+1
diff --git a/docs/examples/userguide/numpy_ufuncs/ufunc_fused.pyx b/docs/examples/userguide/numpy_ufuncs/ufunc_fused.pyx
new file mode 100644
index 000000000..3baf58136
--- /dev/null
+++ b/docs/examples/userguide/numpy_ufuncs/ufunc_fused.pyx
@@ -0,0 +1,7 @@
+# tag: numpy
+cimport cython
+
+
+@cython.ufunc
+cdef cython.numeric generic_add_one(cython.numeric x):
+    return x+1
diff --git a/docs/src/userguide/numpy_ufuncs.rst b/docs/src/userguide/numpy_ufuncs.rst
index a46499072..b5df36861 100644
--- a/docs/src/userguide/numpy_ufuncs.rst
+++ b/docs/src/userguide/numpy_ufuncs.rst
@@ -1,13 +1,16 @@
-.. highlight:: python
+.. highlight:: cython
 
 .. _numpy-ufuncs:
 
-**************************
+*********************
 Creating Numpy ufuncs
-**************************
+*********************
+
+.. include::
+    ../two-syntax-variants-used
 
 Numpy supports a `special type of function called a ufunc
-<https://numpy.org/doc/stable/reference/ufuncs.html>`_ . 
+<https://numpy.org/doc/stable/reference/ufuncs.html>`_ .
 These support array broadcasting (i.e. the ability to handle arguments with any
 number of dimensions), alongside other useful features.
 
@@ -16,41 +19,52 @@ decorator. The input and output argument types should be scalar variables ("gene
 not yet supported) and should either by Python objects or simple numeric types. The body
 of such a function is inserted into an efficient, compiled loop.
 
-.. code-block:: cython
+.. tabs::
+
+    .. group-tab:: Pure Python
 
-    cimport cython
+        .. literalinclude:: ../../examples/userguide/numpy_ufuncs/ufunc.py
+            :lines: 2-
 
-    @cython.ufunc
-    cdef double add_one(double x):
-        # of course, this simple operation can already by done efficiently in Numpy!
-        return x+1  
+    .. group-tab:: Cython
+
+        .. literalinclude:: ../../examples/userguide/numpy_ufuncs/ufunc.pyx
+            :lines: 2-
 
 You can have as many arguments to your function as you like. If you want to have multiple
 output arguments then you can use the :ref:`ctuple syntax<typing_types>`:
 
-.. code-block:: cython
+.. tabs::
+
+    .. group-tab:: Pure Python
 
-    cimport cython
+        .. literalinclude:: ../../examples/userguide/numpy_ufuncs/ufunc_ctuple.py
+            :lines: 2-
 
-    @cython.ufunc
-    cdef (int, int) add_one_add_two(int x):
-        return x+1, x+2
+    .. group-tab:: Cython
+
+        .. literalinclude:: ../../examples/userguide/numpy_ufuncs/ufunc_ctuple.pyx
+            :lines: 2-
 
 If you want to accept multiple different argument types then you can use :ref:`fusedtypes`:
 
-.. code-block:: cython
+.. tabs::
+
+    .. group-tab:: Pure Python
+
+        .. literalinclude:: ../../examples/userguide/numpy_ufuncs/ufunc_fused.py
+            :lines: 2-
+
+    .. group-tab:: Cython
 
-    cimport cython
+        .. literalinclude:: ../../examples/userguide/numpy_ufuncs/ufunc_fused.pyx
+            :lines: 2-
 
-    @cython.ufunc
-    cdef cython.numeric generic_add_one(cython.numeric x):
-        return x+1
-        
-Finally, if you declare the ``cdef`` function as ``nogil`` then Cython will release the
+Finally, if you declare the ``cdef``/``@cfunc`` function as ``nogil`` then Cython will release the
 :term:`GIL<Global Interpreter Lock or GIL>` once in the generated ufunc. This is a slight difference
 from the general behaviour of ``nogil`` functions (they generally do not automatically
 release the GIL, but instead can be run without the GIL).
 
 This feature relies on Numpy. Therefore if you create a ufunc in
-Cython, you must have the Numpy headers available when you build the generated C code, and 
+Cython, you must have the Numpy headers available when you build the generated C code, and
 users of your module must have Numpy installed when they run it.