Add a warning in the docs that "conditional compilation" is not a good way to...

Add a warning in the docs that "conditional compilation" is not a good way to do most things that users commonly do with it.

See the discussion in https://github.com/cython/cython/issues/4287

docs/src/userguide/external_C_code.rst

@@ -365,6 +365,9 @@ 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.
 
+
+.. _verbatim_c:
+
 Including verbatim C code
 -------------------------
 

docs/src/userguide/language_basics.rst

@@ -1284,10 +1284,17 @@ Conditional Compilation
 Some features are available for conditional compilation and compile-time
 constants within a Cython source file.
 
+.. note::
+
+    This feature has very little use cases.  Specifically, is is not a good
+    way to adapt code to platform and environment.  Use code generation or
+    (preferably) C compile time adaptation for this.  See, for example,
+    :ref:`verbatim_c`.
+
 .. note::
 
     Cython currently does not support conditional compilation and compile-time
-    definitions in Pure Python mode.
+    definitions in Pure Python mode.  As it stands, this is unlikely to change.
 
 Compile-Time Definitions
 ------------------------