Updates and cosmetic changes for config doc

doc/library/config.txt

@@ -25,12 +25,12 @@ the :envvar:`THEANO_FLAGS` environment variable.
 
 The order of precedence is:
 
-1. an assignment to theano.config.<property>
+1. an assignment to ``theano.config.<property>``
 2. an assignment in :envvar:`THEANO_FLAGS`
 3. an assignment in the .theanorc file (or the file indicated in :envvar:`THEANORC`)
 
 You can print out the current/effective configuration at any time by printing
-theano.config.  For example, to see a list  of all active configuration
+``theano.config``.  For example, to see a list  of all active configuration
 variables, type this from the command-line:
 
 .. code-block:: bash
@@ -162,7 +162,7 @@ import theano and print the config variable, as in:
     the GPU.  With PyCUDA version 2011.2.2 or earlier, PyCUDA must
     initialize the GPU before Theano does it.  Setting
     this flag to True, ensure that, but always import PyCUDA.  It can
-    be done manually by importing theano.misc.pycuda_init before
+    be done manually by importing ``theano.misc.pycuda_init`` before
     Theano initialize the GPU device.  Newer version of PyCUDA
     (currently only in the trunk) don't have this restriction.
 
@@ -184,19 +184,19 @@ import theano and print the config variable, as in:
 
 .. attribute:: floatX
 
-    String value: either 'float64' or 'float32'
+    String value: ``'float64'``, ``'float32'``, or ``'float16'`` (with limited support)
 
-    Default: 'float64'
+    Default: ``'float64'``
 
-    This sets the default dtype returned by tensor.matrix(), tensor.vector(),
-    and similar functions.  It also sets the default theano bit width for
+    This sets the default dtype returned by ``tensor.matrix()``, ``tensor.vector()``,
+    and similar functions.  It also sets the default Theano bit width for
     arguments passed as Python floating-point numbers.
 
 .. attribute:: warn_float64
 
-    String value: either 'ignore', 'warn', 'raise' or 'pdb'
+    String value: either ``'ignore'``, ``'warn'``, ``'raise'``, or ``'pdb'``
 
-    Default: 'ignore'
+    Default: ``'ignore'``
 
     When creating a TensorVariable with dtype float64, what should be done?
     This is useful to help find upcast to float64 in user code.
@@ -235,7 +235,7 @@ import theano and print the config variable, as in:
 
     Allow/disallow gc inside of Scan.
 
-    If config.allow_gc is ``True``, but config.scan.allow_gc is
+    If :attr:`config.allow_gc` is ``True``, but :attr:`config.scan.allow_gc` is
     ``False``, then we will gc the inner of scan after all
     iterations. This is the default.
 
@@ -249,10 +249,10 @@ import theano and print the config variable, as in:
 
 .. attribute:: openmp
 
-    Bool value: either True or False
+    Bool value: either ``True`` or ``False``
 
-    Default: True if the environment variable OMP_NUM_THREADS!=1 or
-             if we detect more than 1 CPU core. Otherwise False.
+    Default: ``True`` if the environment variable OMP_NUM_THREADS!=1 or
+             if we detect more than 1 CPU core. Otherwise ``False``.
 
     Enable or not parallel computation on the CPU with OpenMP.
     It is the default value used when creating an Op that support it.
@@ -268,9 +268,9 @@ import theano and print the config variable, as in:
 
 .. attribute:: cast_policy
 
-    String value: either 'numpy+floatX' or 'custom'
+    String value: either ``'numpy+floatX'`` or ``'custom'``
 
-    Default: 'custom'
+    Default: ``'custom'``
 
     This specifies how data types are implicitly figured out in Theano, e.g. for
     constants or in the results of arithmetic operations. The 'custom' value
@@ -286,7 +286,7 @@ import theano and print the config variable, as in:
     At the moment it behaves differently from numpy in the following
     situations:
 
-    * Depending on the value of ``config.int_division``, the resulting type
+    * Depending on the value of :attr:`config.int_division`, the resulting type
       of a division of integer types with the ``/`` operator may not match
       that of numpy.
     * On mixed scalar / array operations, numpy tries to prevent the scalar
@@ -298,9 +298,9 @@ import theano and print the config variable, as in:
 
 .. attribute:: int_division
 
-    String value: either 'int', 'floatX' or 'raise'
+    String value: either ``'int'``, ``'floatX'``, or ``'raise'``
 
-    Default: 'int'
+    Default: ``'int'``
 
     Specifies what to do when one tries to compute ``x / y``, where both ``x`` and
     ``y`` are of integer types (possibly unsigned). 'int' means an integer is
@@ -313,10 +313,10 @@ import theano and print the config variable, as in:
 
 .. attribute:: mode
 
-    String value: 'Mode', 'ProfileMode'(deprecated), 'DebugMode', 'FAST_RUN',
-    'FAST_COMPILE'
+    String value: ``'Mode'``, ``'ProfileMode'`` (deprecated), ``'DebugMode'``, ``'FAST_RUN'``,
+    ``'FAST_COMPILE'``
 
-    Default 'Mode'
+    Default: ``'Mode'``
 
     This sets the default compilation mode for theano functions. By default the
     mode Mode is equivalent to FAST_RUN. See Config attribute linker and optimizer.
@@ -325,7 +325,7 @@ import theano and print the config variable, as in:
 
     Bool value: either True or False
 
-    Default False
+    Default: False
 
     Do the vm/cvm linkers profile the execution time of Theano functions?
 
@@ -335,7 +335,7 @@ import theano and print the config variable, as in:
 
     Bool value: either True or False
 
-    Default False
+    Default: False
 
     Do the vm/cvm linkers profile the memory usage of Theano functions?
     It only works when profile=True.
@@ -344,7 +344,7 @@ import theano and print the config variable, as in:
 
     Bool value: either True or False
 
-    Default False
+    Default: False
 
     Do the vm/cvm linkers profile the optimization phase when compiling a Theano function?
     It only works when profile=True.
@@ -372,17 +372,17 @@ import theano and print the config variable, as in:
 
     Bool value: either True or False
 
-    Default False
+    Default: False
 
     Does the memory profile print the min peak memory usage?
     It only works when profile=True, profile_memory=True
 
 .. attribute:: config.profiling.destination
 
-    String value: 'stderr', 'stdout', or a name of a
+    String value: ``'stderr'``, ``'stdout'``, or a name of a
     file to be created
 
-    Default 'stderr'
+    Default: ``'stderr'``
 
     Name of the destination file for the profiling output.
     The profiling output can be either directed to stderr
@@ -392,7 +392,7 @@ import theano and print the config variable, as in:
 
     Bool value: either True or False
 
-    Default False
+    Default: False
 
     Do a debugprint of the profiled functions
 
@@ -400,7 +400,7 @@ import theano and print the config variable, as in:
 
     Bool value: either True or False
 
-    Default False
+    Default: False
 
     Do we ignore the first call to a Theano function while profiling.
 
@@ -408,7 +408,7 @@ import theano and print the config variable, as in:
 
     Bool value: either True or False
 
-    Default False
+    Default: False
 
     This makes the compilation use the
     `amdlibm <http://developer.amd.com/cpu/libraries/libm/>`__
@@ -488,26 +488,26 @@ import theano and print the config variable, as in:
 
 .. attribute:: linker
 
-    String value: 'c|py', 'py', 'c', 'c|py_nogc'
+    String value: ``'c|py'``, ``'py'``, ``'c'``, ``'c|py_nogc'``
 
-    Default: 'c|py'
+    Default: ``'c|py'``
 
     When the mode is Mode, it sets the default linker used.
     See :ref:`using_modes` for a comparison of the different linkers.
 
 .. attribute:: optimizer
 
-    String value: 'fast_run', 'merge', 'fast_compile', 'None'
+    String value: ``'fast_run'``, ``'merge'``, ``'fast_compile'``, ``'None'``
 
-    Default: 'fast_run'
+    Default: ``'fast_run'``
 
     When the mode is Mode, it sets the default optimizer used.
 
 .. attribute:: on_opt_error
 
-    String value: 'warn', 'raise', 'pdb' or 'ignore'
+    String value: ``'warn'``, ``'raise'``, ``'pdb'`` or ``'ignore'``
 
-    Default: 'warn'
+    Default: ``'warn'``
 
     When a crash occurs while trying to apply some optimization, either warn
     the user and skip this optimization ('warn'), raise the exception
@@ -520,9 +520,9 @@ import theano and print the config variable, as in:
 
 .. attribute:: assert_no_cpu_op
 
-    String value: 'ignore' or 'warn' or 'raise' or 'pdb'
+    String value: ``'ignore'`` or ``'warn'`` or ``'raise'`` or ``'pdb'``
 
-    Default: 'ignore'
+    Default: ``'ignore'``
 
     If there is a CPU op in the computational graph, depending on its value;
     this flag can either raise a warning, an exception or stop the
@@ -530,9 +530,9 @@ import theano and print the config variable, as in:
 
 .. attribute:: on_shape_error
 
-    String value: 'warn' or 'raise'
+    String value: ``'warn'`` or ``'raise'``
 
-    Default: 'warn'
+    Default: ``'warn'``
 
     When an exception is raised when inferring the shape of some apply
     node, either warn the user and use a default value ('warn'), or
@@ -541,9 +541,10 @@ import theano and print the config variable, as in:
 
 .. attribute:: config.warn.ignore_bug_before
 
-    String value: 'None', 'all', '0.3', '0.4', '0.4.1', '0.5', '0.6', '0.7'
+    String value: ``'None'``, ``'all'``, ``'0.3'``, ``'0.4'``, ``'0.4.1'``, ``'0.5'``,
+    ``'0.6'``, ``'0.7'``, ``'0.8'``, ``'0.8.1'``, ``'0.8.2'``
 
-    Default: '0.7'
+    Default: ``'0.7'``
 
     When we fix a Theano bug that generated bad results under some
     circumstances, we also make Theano raise a warning when it encounters
@@ -559,8 +560,8 @@ import theano and print the config variable, as in:
     You can set its value to the first version of Theano
     that you used (probably 0.3 or higher)
 
-    `None` means that all warnings will be displayed.
-    `all` means all warnings will be ignored.
+    ``'None'`` means that all warnings will be displayed.
+    ``'all'`` means all warnings will be ignored.
 
     It is recommended that you put a version, so that you will see future
     warnings.
@@ -580,7 +581,7 @@ import theano and print the config variable, as in:
 
 .. attribute:: compiledir_format
 
-    Default: "compiledir_%(platform)s-%(processor)s-%(python_version)s-%(python_bitwidth)s"
+    Default: ``"compiledir_%(platform)s-%(processor)s-%(python_version)s-%(python_bitwidth)s"``
 
     This is a Python format string that specifies the subdirectory
     of ``config.base_compiledir`` in which to store platform-dependent
@@ -601,17 +602,17 @@ import theano and print the config variable, as in:
 
 .. attribute:: config.blas.ldflags
 
-    Default: '-lblas'
+    Default: ``'-lblas'``
 
     Link arguments to link against a (Fortran) level-3 blas
-    implementation.  The default will test if '-lblas' work. If not,
-    we will disable our c code for BLAS.
+    implementation.  The default will test if ``'-lblas'`` works. If not,
+    we will disable our C code for BLAS.
 
 .. attribute:: config.experimental.local_alloc_elemwise_assert
 
-    Bool value: either True or False
+    Bool value: either ``True`` or ``False``
 
-    Default: True
+    Default: ``True``
 
     When the local_alloc_optimization is applied, add an assert to highlight
     shape errors.
@@ -623,21 +624,23 @@ import theano and print the config variable, as in:
 
 .. attribute:: config.cuda.root
 
-    Default: $CUDA_ROOT or failing that, "/usr/local/cuda"
+    Default: $CUDA_ROOT or failing that, ``"/usr/local/cuda"``
 
     A directory with bin/, lib/, include/ folders containing cuda utilities.
 
 .. attribute:: config.dnn.enabled
 
-  String value: ``auto``, ``True``, ``False``
+    String value: ``'auto'``, ``'True'``, ``'False'``
 
-  Default: ``auto``
+    Default: ``'auto'``
 
-  If ``auto``, automatically detect and use [cuDNN](https://developer.nvidia.com/cudnn) if it is available.  If cuDNN is unavailable, raise no error.
+    If ``'auto'``, automatically detect and use
+    `cuDNN <https://developer.nvidia.com/cudnn>`_ if it is available.
+    If cuDNN is unavailable, raise no error.
 
-  If ``True``, require the use of cuDNN.  If cuDNN is unavailable, raise an error.
+    If ``'True'``, require the use of cuDNN.  If cuDNN is unavailable, raise an error.
 
-  If ``False``, do not use cuDNN or check if it is available.
+    If ``'False'``, do not use cuDNN or check if it is available.
 
 .. attribute:: config.dnn.conv.workmem
 
@@ -652,14 +655,14 @@ import theano and print the config variable, as in:
 .. attribute:: config.dnn.conv.algo_fwd
 
     String value:
-    ``small``, ``none``, ``large``, ``fft``, ``fft_tiling``,
-    ``winograd``, ``guess_once``, ``guess_on_shape_change``,
-    ``time_once``, ``time_on_shape_change``.
+    ``'small'``, ``'none'``, ``'large'``, ``'fft'``, ``'fft_tiling'``,
+    ``'winograd'``, ``'guess_once'``, ``'guess_on_shape_change'``,
+    ``'time_once'``, ``'time_on_shape_change'``.
 
-    Default: ``small``
+    Default: ``'small'``
 
-    3d convolution only support ``none``, ``winograd``, ``guess_once``,
-    ``guess_on_shape_change``, ``time_once``, ``time_on_shape_change``.
+    3d convolution only support ``'none'``, ``'winograd'``, ``'guess_once'``,
+    ``'guess_on_shape_change'``, ``'time_once'``, ``'time_on_shape_change'``.
 
 .. attribute:: config.dnn.conv.algo_bwd
 
@@ -669,26 +672,26 @@ import theano and print the config variable, as in:
 .. attribute:: config.dnn.conv.algo_bwd_filter
 
     String value:
-    ``none``, ``deterministic``, ``fft``, ``small``, ``guess_once``,
-    ``guess_on_shape_change``, ``time_once``, ``time_on_shape_change``.
+    ``'none'``, ``'deterministic'``, ``'fft'``, ``'small'``, ``'guess_once'``,
+    ``'guess_on_shape_change'``, ``'time_once'``, ``'time_on_shape_change'``.
 
-    Default: ``none``
+    Default: ``'none'``
 
-    3d convolution only supports ``none``, ``guess_once``,
-    ``guess_on_shape_change``, ``time_once``, ``time_on_shape_change``.
+    3d convolution only supports ``'none'``, ``'guess_once'``,
+    ``'guess_on_shape_change'``, ``'time_once'``, ``'time_on_shape_change'``.
 
 .. attribute:: config.dnn.conv.algo_bwd_data
 
     String value:
-    ``none``, ``deterministic``, ``fft``, ``fft_tiling``, ``winograd``,
-    ``guess_once``, ``guess_on_shape_change``, ``time_once``,
-    ``time_on_shape_change``.
+    ``'none'``, ``'deterministic'``, ``'fft'``, ``'fft_tiling'``, ``'winograd'``,
+    ``'guess_once'``, ``'guess_on_shape_change'``, ``'time_once'``,
+    ``'time_on_shape_change'``.
 
-    Default: ``none``
+    Default: ``'none'``
 
-    3d convolution only support ``none``, ``winograd``,
-    ``guess_once``, ``guess_on_shape_change``, ``time_once``,
-    ``time_on_shape_change``.
+    3d convolution only support ``'none'``, ``'winograd'``,
+    ``'guess_once'``, ``'guess_on_shape_change'``, ``'time_once'``,
+    ``'time_on_shape_change'``.
 
 .. attribute:: config.gcc.cxxflags
 
@@ -717,16 +720,18 @@ import theano and print the config variable, as in:
 
     Default: False
 
-    If true, this will enable fastmath (`--use_fast_math
-    <http://docs.nvidia.com/cuda/cuda-compiler-driver-nvcc/#options-for-steering-cuda-compilation>`_)
+    If true, this will enable fastmath (|use_fast_math|_)
     mode for compiled cuda code which makes div and sqrt faster at the
     cost of precision.  This also disables support for denormal
     numbers. This can cause NaN. So if you have NaN and use this flag,
     try to disable it.
 
+    .. |use_fast_math| replace:: ``--use-fast-math``
+    .. _use_fast_math: http://docs.nvidia.com/cuda/cuda-compiler-driver-nvcc/#options-for-steering-cuda-compilation
+
 .. attribute:: config.optimizer_excluding
 
-    Default: ""
+    Default: ``""``
 
     A list of optimizer tags that we don't want included in the default Mode.
     If multiple tags, separate them by ':'.
@@ -738,7 +743,7 @@ import theano and print the config variable, as in:
 
 .. attribute:: optimizer_including
 
-    Default: ""
+    Default: ``""``
 
     A list of optimizer tags that we want included in the default Mode.
     If multiple tags, separate them by ':'.
@@ -747,7 +752,7 @@ import theano and print the config variable, as in:
 
 .. attribute:: optimizer_requiring
 
-    Default: ""
+    Default: ``""``
 
     A list of optimizer tags that we require for optimizer in the default Mode.
     If multiple tags, separate them by ':'.
@@ -756,17 +761,17 @@ import theano and print the config variable, as in:
 
 .. attribute:: optimizer_verbose
 
-    Bool value: either True or False
+    Bool value: either ``True`` or ``False``
 
-    Default: False
+    Default: ``False``
 
     When True, we print on the stdout the optimization applied.
 
 .. attribute:: nocleanup
 
-    Bool value: either True or False
+    Bool value: either ``True`` or ``False``
 
-    Default: False
+    Default: ``False``
 
     If False, source code files are removed when they are not needed anymore.
     This means files whose compilation failed are deleted.
@@ -859,7 +864,7 @@ import theano and print the config variable, as in:
 
 .. attribute:: numpy
 
-    This section contains different attributes for configuring numpy's
+    This section contains different attributes for configuring NumPy's
     behaviour, described by `numpy.seterr
     <http://docs.scipy.org/doc/numpy/reference/generated/numpy.seterr.html>`__.
 
@@ -874,7 +879,7 @@ import theano and print the config variable, as in:
     <http://docs.scipy.org/doc/numpy/reference/generated/numpy.seterr.html>`__.
 
     ``'None'`` means that numpy's default behaviour will not be changed (unless
-    one of the other `config.numpy.seterr_*` overrides it), but this behaviour
+    one of the other ``config.numpy.seterr_*`` overrides it), but this behaviour
     can change between numpy releases.
 
     This flag sets the default behaviour for all kinds of floating-pont
@@ -943,9 +948,9 @@ import theano and print the config variable, as in:
     dimension mis-match), **before** optimizations are applied.
 
     Theano will execute the graph using the Constants and/or shared variables
-    provided by the user. Purely symbolic variables (e.g. x = T.dmatrix()) can be
+    provided by the user. Purely symbolic variables (e.g. ``x = T.dmatrix()``) can be
     augmented with test values, by writing to their ``'tag.test_value'``
-    attribute (e.g. x.tag.test_value = numpy.random.rand(5,4)).
+    attribute (e.g. ``x.tag.test_value = numpy.random.rand(5, 4)``).
 
     When not ``'off'``, the value of this option dictates what happens when
     an Op's inputs do not provide appropriate test values:
@@ -965,7 +970,7 @@ import theano and print the config variable, as in:
 
     Bool value, default: False
 
-    If ``'True'``, Theano will override the '__str__' method of its variables
+    If ``'True'``, Theano will override the ``__str__`` method of its variables
     to also print the tag.test_value when this is available.
 
 .. attribute:: reoptimize_unpickled_function
@@ -1000,26 +1005,26 @@ import theano and print the config variable, as in:
     Bool value, default: False
 
     If True, will print a warning when compiling one or more Op with C
-    code that can't be cached because there is no c_code_cache_version()
+    code that can't be cached because there is no ``c_code_cache_version()``
     function associated to at least one of those Ops.
 
 .. attribute:: config.cmodule.remove_gxx_opt
 
-    Bool value, default: False
+    Bool value, default: ``False``
 
-    If True, will remove the -O* parameter passed to g++.
+    If True, will remove the ``-O*`` parameter passed to g++.
     This is useful to debug in gdb modules compiled by Theano.
-    The parameter -g is passed by default to g++.
+    The parameter ``-g`` is passed by default to g++.
 
 .. attribute:: config.cmodule.compilation_warning
 
-    Bool value, default: False
+    Bool value, default: ``False``
 
     If True, will print compilation warnings.
 
 .. attribute:: config.cmodule.preload_cache
 
-    Bool value, default: False
+    Bool value, default: ``False``
 
     If set to True, will preload the C module cache at import time
 

theano/configdefaults.py

@@ -651,8 +651,8 @@ AddConfigVar('warn.ignore_bug_before',
               "bugs found after that version. "
               "Warning for specific bugs can be configured with specific "
               "[warn] flags."),
-             EnumStr('0.7', 'None', 'all', '0.3', '0.4', '0.4.1', '0.5', '0.7',
-                     '0.8',
+             EnumStr('0.7', 'None', 'all', '0.3', '0.4', '0.4.1', '0.5', '0.6',
+                     '0.7', '0.8', '0.8.1', '0.8.2',
                      allow_override=False),
              in_c_key=False)