Repository: cython/cython
Pull request: Added epilog to cythonize listing supported environment variables
I suppose we can close #1711 by accepting this PR.


Problem statement:
Make the cythonize command line more useful
A couple of more common build options, such as `--numpy`, `--include_path`, `--libraries`, `--cflags`, `--ldflags` should be added to `cythonize` command line so that it can be used easily for the majority of building tasks. 

Setting up a `setup.py` script for every `pyx` file I need to write is really, really tedious, which put me off from cython for years before I finally tried it for the first time (and that was in IPython notebook with cython magic, so I still don't know how to write `setup.py`). I am sure that many beginners to cython are just scared of the complicated build process like me, and never have the chance to actually try it. Please make it more accessible.

The `%%cython` magic in IPython has much better sane defaults and useful command line options than the `cythonize` script.

Hints from issue discussion:
I extracted the cython magic into a separate script at https://github.com/netheril96/utilities/blob/master/mycython.py.
Just noting here something I noticed, cythonize CLI interface actually honors environment variables such as CC, CXX, LDSHARED, CFLAGS, CPPFLAGS, LDFLAGS... I assume this isn't documented under cythonize since this feature is provided by distutils.

Example:
```
~/tmp$ CFLAGS="-O3 -g0" CPPFLAGS="-DMYDEF1 -DMYDEF2" LDFLAGS="-lz" cythonize -3 -i test.pyx 
running build_ext
building 'test' extension
creating /home/omer/tmp/tmpvkvr9kqr/home
creating /home/omer/tmp/tmpvkvr9kqr/home/omer
creating /home/omer/tmp/tmpvkvr9kqr/home/omer/tmp
x86_64-linux-gnu-gcc -pthread -DNDEBUG -g -fwrapv -O2 -Wall -O3 -g0 -DMYDEF1 -DMYDEF2 -fPIC -I/usr/include/python3.7m -c /home/omer/tmp/test.c -o /home/omer/tmp/tmpvkvr9kqr/home/omer/tmp/test.o
x86_64-linux-gnu-gcc -pthread -shared -Wl,-O1 -Wl,-Bsymbolic-functions -Wl,-z,relro -lz -O3 -g0 -DMYDEF1 -DMYDEF2 /home/omer/tmp/tmpvkvr9kqr/home/omer/tmp/test.o -o /home/omer/tmp/test.cpython-37m-x86_64-linux-gnu.so
```

Additionally, setting DISTUTILS_DEBUG environment variable enables printing extra debug info.

Commit message: Remove whitespace from empty line.

Co-authored-by: da-woods <dw-git@d-woods.co.uk>

Patch to review:
diff --git a/Cython/Build/Cythonize.py b/Cython/Build/Cythonize.py
index 1f79589f875..554e3888a5f 100644
--- a/Cython/Build/Cythonize.py
+++ b/Cython/Build/Cythonize.py
@@ -121,10 +121,17 @@ def run_distutils(args):
 
 
 def create_args_parser():
-    from argparse import ArgumentParser
+    from argparse import ArgumentParser, RawDescriptionHelpFormatter
     from ..Compiler.CmdLine import ParseDirectivesAction, ParseOptionsAction, ParseCompileTimeEnvAction
 
-    parser = ArgumentParser()
+    parser = ArgumentParser(
+        formatter_class=RawDescriptionHelpFormatter,
+        epilog="""Environment variables:
+  CYTHON_FORCE_REGEN: if set to 1, forces cythonize to regenerate the output files regardless
+        of modification times and changes.
+  Environment variables accepted by setuptools are supported to configure the C compiler and build:
+  https://setuptools.pypa.io/en/latest/userguide/ext_modules.html#compiler-and-linker-options"""
+    )
 
     parser.add_argument('-X', '--directive', metavar='NAME=VALUE,...',
                       dest='directives', default={}, type=str,


Code review comments:
diff_hunk: @@ -121,10 +121,17 @@ def run_distutils(args):
 
 
 def create_args_parser():
-    from argparse import ArgumentParser
+    from argparse import ArgumentParser, RawDescriptionHelpFormatter
     from ..Compiler.CmdLine import ParseDirectivesAction, ParseOptionsAction, ParseCompileTimeEnvAction
 
-    parser = ArgumentParser()
+    parser = ArgumentParser(
+        formatter_class=RawDescriptionHelpFormatter,
+        epilog="""Environment variables:
+  CYTHON_FORCE_REGEN: if set to 1, forces cythonize to regenerate the output files regardless
path: Cython/Build/Cythonize.py
text: @user1:
```suggestion
        epilog="""\
Environment variables:
  CYTHON_FORCE_REGEN: if set to 1, forces cythonize to regenerate the output files regardless
```