Added the docs for the compiler options. Used autodata to avoid duplication of...

Added the docs for the compiler options. Used autodata to avoid duplication of the options descriptions in the docs and in the python file.

Cython/Compiler/Options.py

@@ -28,94 +28,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

@@ -316,6 +316,50 @@ customize your build.
                                 ``compiler_directives={'embedsignature': True}``.
                                 See :ref:`compiler-directives`.
 
+
+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
 ----------------------------