Merge pull request #2291 from gabrieldemarmiesse/compiler_options

Added the docs for the compiler options.

Cython/Compiler/Options.py

@@ -29,94 +29,121 @@ class ShouldBeFromDirective(object):
         "Illegal access of '%s' from Options module rather than directive '%s'"
         % (self.options_name, self.directive_name))
 
-# Include docstrings.
+
+""" 
+The members of this module are documented using autodata in 
+Cython/docs/src/reference/compilation.rst.
+See http://www.sphinx-doc.org/en/master/ext/autodoc.html#directive-autoattribute
+for how autodata works. 
+Descriptions of those members should start with a #:
+Donc forget to keep the docs in sync by removing and adding
+the members in both this file and the .rst file.
+"""
+
+#: Whether or not to include docstring in the Python extension. If False, the binary size
+#: will be smaller, but the ``__doc__`` attribute of any class or function will be an
+#: empty string.
 docstrings = True
 
-# Embed the source code position in the docstrings of functions and classes.
+#: Embed the source code position in the docstrings of functions and classes.
 embed_pos_in_docstring = False
 
-# Copy the original source code line by line into C code comments
-# in the generated code file to help with understanding the output.
+#: Copy the original source code line by line into C code comments
+#: in the generated code file to help with understanding the output.
+#: This is also required for coverage analysis.
 emit_code_comments = True
 
-pre_import = None  # undocumented
+# undocumented
+pre_import = None
 
-# Decref global variables in this module on exit for garbage collection.
-# 0: None, 1+: interned objects, 2+: cdef globals, 3+: types objects
-# Mostly for reducing noise in Valgrind, only executes at process exit
-# (when all memory will be reclaimed anyways).
+#: Decref global variables in each module on exit for garbage collection.
+#: 0: None, 1+: interned objects, 2+: cdef globals, 3+: types objects
+#: Mostly for reducing noise in Valgrind, only executes at process exit
+#: (when all memory will be reclaimed anyways).
 generate_cleanup_code = False
 
-# Should tp_clear() set object fields to None instead of clearing them to NULL?
+#: Should tp_clear() set object fields to None instead of clearing them to NULL?
 clear_to_none = True
 
-# Generate an annotated HTML version of the input source files.
+#: Generate an annotated HTML version of the input source files for debugging and optimisation purposes.
+#: This has the same effect as the ``annotate`` argument in :func:`cythonize`.
 annotate = False
 
 # When annotating source files in HTML, include coverage information from
 # this file.
 annotate_coverage_xml = None
 
-# This will abort the compilation on the first error occurred rather than trying
-# to keep going and printing further error messages.
+#: This will abort the compilation on the first error occurred rather than trying
+#: to keep going and printing further error messages.
 fast_fail = False
 
-# Make all warnings into errors.
+#: Turn all warnings into errors.
 warning_errors = False
 
-# Make unknown names an error.  Python raises a NameError when
-# encountering unknown names at runtime, whereas this option makes
-# them a compile time error.  If you want full Python compatibility,
-# you should disable this option and also 'cache_builtins'.
+#: Make unknown names an error.  Python raises a NameError when
+#: encountering unknown names at runtime, whereas this option makes
+#: them a compile time error.  If you want full Python compatibility,
+#: you should disable this option and also 'cache_builtins'.
 error_on_unknown_names = True
 
-# Make uninitialized local variable reference a compile time error.
-# Python raises UnboundLocalError at runtime, whereas this option makes
-# them a compile time error. Note that this option affects only variables
-# of "python object" type.
+#: Make uninitialized local variable reference a compile time error.
+#: Python raises UnboundLocalError at runtime, whereas this option makes
+#: them a compile time error. Note that this option affects only variables
+#: of "python object" type.
 error_on_uninitialized = True
 
-# This will convert statements of the form "for i in range(...)"
-# to "for i from ..." when i is a cdef'd integer type, and the direction
-# (i.e. sign of step) can be determined.
-# WARNING: This may change the semantics if the range causes assignment to
-# i to overflow. Specifically, if this option is set, an error will be
-# raised before the loop is entered, whereas without this option the loop
-# will execute until an overflowing value is encountered.
+#: This will convert statements of the form ``for i in range(...)``
+#: to ``for i from ...`` when ``i`` is a C integer type, and the direction
+#: (i.e. sign of step) can be determined.
+#: WARNING: This may change the semantics if the range causes assignment to
+#: i to overflow. Specifically, if this option is set, an error will be
+#: raised before the loop is entered, whereas without this option the loop
+#: will execute until an overflowing value is encountered.
 convert_range = True
 
-# Perform lookups on builtin names only once, at module initialisation
-# time.  This will prevent the module from getting imported if a
-# builtin name that it uses cannot be found during initialisation.
+#: Perform lookups on builtin names only once, at module initialisation
+#: time.  This will prevent the module from getting imported if a
+#: builtin name that it uses cannot be found during initialisation.
+#: Default is True.
+#: Note that some legacy builtins are automatically remapped
+#: from their Python 2 names to their Python 3 names by Cython
+#: when building in Python 3.x,
+#: so that they do not get in the way even if this option is enabled.
 cache_builtins = True
 
-# Generate branch prediction hints to speed up error handling etc.
+#: Generate branch prediction hints to speed up error handling etc.
 gcc_branch_hints = True
 
-# Enable this to allow one to write your_module.foo = ... to overwrite the
-# definition if the cpdef function foo, at the cost of an extra dictionary
-# lookup on every call.
-# If this is false it generates only the Python wrapper and no override check.
+#: Enable this to allow one to write ``your_module.foo = ...`` to overwrite the
+#: definition if the cpdef function foo, at the cost of an extra dictionary
+#: lookup on every call.
+#: If this is false it generates only the Python wrapper and no override check.
 lookup_module_cpdef = False
 
-# Whether or not to embed the Python interpreter, for use in making a
-# standalone executable or calling from external libraries.
-# This will provide a method which initialises the interpreter and
-# executes the body of this module.
+#: Whether or not to embed the Python interpreter, for use in making a
+#: standalone executable or calling from external libraries.
+#: This will provide a C function which initialises the interpreter and
+#: executes the body of this module.
+#: See `this demo <https://github.com/cython/cython/tree/master/Demos/embed>`_
+#: for a concrete example.
+#: If true, the initialisation function is the C main() function, but
+#: this option can also be set to a non-empty string to provide a function name explicitly.
+#: Default is False.
 embed = None
 
 # In previous iterations of Cython, globals() gave the first non-Cython module
 # globals in the call stack.  Sage relies on this behavior for variable injection.
 old_style_globals = ShouldBeFromDirective('old_style_globals')
 
-# Allows cimporting from a pyx file without a pxd file.
+#: Allows cimporting from a pyx file without a pxd file.
 cimport_from_pyx = False
 
-# max # of dims for buffers -- set lower than number of dimensions in numpy, as
-# slices are passed by value and involve a lot of copying
+#: Maximum number of dimensions for buffers -- set lower than number of
+#: dimensions in numpy, as
+#: slices are passed by value and involve a lot of copying.
 buffer_max_dims = 8
 
-# Number of function closure instances to keep in a freelist (0: no freelists)
+#: Number of function closure instances to keep in a freelist (0: no freelists)
 closure_freelist_size = 8
 
 

docs/src/reference/compilation.rst

@@ -253,6 +253,50 @@ customize your build.
 .. autofunction:: Cython.Build.cythonize
 
 
+
+Compiler options
+----------------
+
+Compiler options can be set in the :file:`setup.py`, before calling :func:`cythonize`,
+like this::
+
+    from distutils.core import setup
+
+    from Cython.Build import cythonize
+    from Cython.Compiler import Options
+
+    Options.docstrings = False
+
+    setup(
+        name = "hello",
+        ext_modules = cythonize("lib.pyx"),
+    )
+
+Here are the options that are available:
+
+.. autodata:: Cython.Compiler.Options.docstrings
+.. autodata:: Cython.Compiler.Options.embed_pos_in_docstring
+.. autodata:: Cython.Compiler.Options.emit_code_comments
+.. pre_import
+.. autodata:: Cython.Compiler.Options.generate_cleanup_code
+.. autodata:: Cython.Compiler.Options.clear_to_none
+.. autodata:: Cython.Compiler.Options.annotate
+.. annotate_coverage_xml
+.. autodata:: Cython.Compiler.Options.fast_fail
+.. autodata:: Cython.Compiler.Options.warning_errors
+.. autodata:: Cython.Compiler.Options.error_on_unknown_names
+.. autodata:: Cython.Compiler.Options.error_on_uninitialized
+.. autodata:: Cython.Compiler.Options.convert_range
+.. autodata:: Cython.Compiler.Options.cache_builtins
+.. autodata:: Cython.Compiler.Options.gcc_branch_hints
+.. autodata:: Cython.Compiler.Options.lookup_module_cpdef
+.. autodata:: Cython.Compiler.Options.embed
+.. old_style_globals
+.. autodata:: Cython.Compiler.Options.cimport_from_pyx
+.. autodata:: Cython.Compiler.Options.buffer_max_dims
+.. autodata:: Cython.Compiler.Options.closure_freelist_size
+
+
 Distributing Cython modules
 ----------------------------