Docs for verbatim C code.

docs/src/userguide/external_C_code.rst

@@ -328,6 +328,41 @@ are entirely on your own with this feature.  If you want to declare a name
 the C file for it, you can do this using a C name declaration.  Consider this
 an advanced feature, only for the rare cases where everything else fails.
 
+Including verbatim C code
+-------------------------
+
+For advanced use cases, Cython allows you to directly write C code
+as "docstring" of a ``cdef extern from`` block::
+
+    cdef extern from *:
+        """
+        /* This is C code which will be put
+         * in the .c file output by Cython */
+        static long square(long x) {return x * x;}
+        #define assign(x, y) ((x) = (y))
+        """
+        long square(long x)
+        void assign(long& x, long y)
+
+The above is essentially equivalent to having the C code in a file
+``header.h`` and writing ::
+
+    cdef extern from "header.h":
+        long square(long x)
+        void assign(long& x, long y)
+
+It is also possible to combine a header file and verbatim C code::
+
+    cdef extern from "badheader.h":
+        """
+        /* This macro breaks stuff */
+        #undef int
+        """
+        # Stuff from badheader.h
+
+In this case, the C code ``#undef int`` is put right after
+``#include "badheader.h"`` in the C code generated by Cython.
+
 
 Using Cython Declarations from C
 ================================