docs: Explain GIL handling in pure.rst (#4650)

docs/src/tutorial/pure.rst

@@ -209,6 +209,46 @@ Here is an example of a :keyword:`cdef` function::
         return a == b
 
 
+Managing the Global Interpreter Lock
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+* ``cython.nogil`` can be used as a context manager or as a decorator to replace the :keyword:`nogil` keyword::
+
+    with cython.nogil:
+        # code block with the GIL released
+
+    @cython.nogil
+    @cython.cfunc
+    def func_released_gil() -> cython.int:
+        # function with the GIL released
+
+* ``cython.gil`` can be used as a context manager to replace the :keyword:`gil` keyword::
+
+    with cython.gil:
+        # code block with the GIL acquired
+
+  .. Note:: Cython currently does not support the ``@cython.with_gil`` decorator.
+
+Both directives accept an optional boolean parameter for conditionally
+releasing or acquiring the GIL. The condition must be constant (at compile time)::
+
+  with cython.nogil(False):
+      # code block with the GIL not released
+
+  @cython.nogil(True)
+  @cython.cfunc
+  def func_released_gil() -> cython.int:
+      # function with the GIL released
+
+  with cython.gil(False):
+      # code block with the GIL not acquired
+
+  with cython.gil(True):
+      # code block with the GIL acquired
+
+A common use case for conditionally acquiring and releasing the GIL are fused types
+that allow different GIL handling depending on the specific type (see :ref:`gil_conditional`).
+
 cimports
 ^^^^^^^^