Clean up doc/library/config.txt

doc/library/config.txt

@@ -14,24 +14,24 @@ Guide
 =====
 
 The config module contains many ``attributes`` that modify Aesara's behavior.  Many of these
-attributes are consulted during the import of the ``aesara`` module and many are assumed to be
-read-only.
+attributes are consulted during the import of the ``aesara`` module, and some
+are assumed to be read-only.
 
 *As a rule, the attributes in this module should not be modified by user code.*
 
-Aesara's code comes with default values for these attributes, but you can
-override them from your ``.aesararc`` file, and override those values in turn by
-the :envvar:`AESARA_FLAGS` environment variable.
+Aesara's code comes with default values for these attributes, but they can be
+overridden via a user's ``.aesararc`` file and the :envvar:`AESARA_FLAGS`
+environment variable.
 
 The order of precedence is:
 
 1. an assignment to ``aesara.config.<property>``
-2. an assignment in :envvar:`AESARA_FLAGS`
-3. an assignment in the ``.aesararc`` file (or the file indicated in :envvar:`AESARARC`)
+2. :envvar:`AESARA_FLAGS`
+3. the ``.aesararc`` file (or the file indicated by :envvar:`AESARARC`)
 
-You can print out the current/effective configuration at any time by printing
-``aesara.config``.  For example, to see a list  of all active configuration
-variables, type this from the command-line:
+The current/effective configuration can be shown at any time by printing the
+object ``aesara.config``.  For example, to see a list of all active
+configuration variables, type this from the command-line:
 
 .. code-block:: bash
 
@@ -43,26 +43,26 @@ Environment Variables
 
 .. envvar:: AESARA_FLAGS
 
-    This is a list of comma-delimited key=value pairs that control
+    This is a list of comma-delimited ``key=value`` pairs that control
     Aesara's behavior.
 
-    For example, in bash, you can override your :envvar:`AESARARC` defaults
-    for <myscript>.py by typing this:
+    For example, in ``bash``, one can override the :envvar:`AESARARC` defaults
+    for a script ``<myscript>.py`` with the following:
 
     .. code-block:: bash
 
         AESARA_FLAGS='floatX=float32,device=cuda0,gpuarray__preallocate=1'  python <myscript>.py
 
     If a value is defined several times in ``AESARA_FLAGS``,
-    the right-most definition is used. So, for instance, if
-    ``AESARA_FLAGS='device=cpu,device=cuda0'``, then cuda0 will be used.
+    the right-most definition is used, so, for instance, if
+    ``AESARA_FLAGS='device=cpu,device=cuda0'`` is set, then ``cuda0`` will be
+    used.
 
 .. envvar:: AESARARC
 
     The location(s) of the ``.aesararc`` file(s) in `ConfigParser` format.
     It defaults to ``$HOME/.aesararc``. On Windows, it defaults to
-    ``$HOME/.aesararc:$HOME/.aesararc.txt`` to make Windows users' life
-    easier.
+    ``$HOME/.aesararc:$HOME/.aesararc.txt``.
 
     Here is the ``.aesararc`` equivalent to the ``AESARA_FLAGS`` in the example above:
 
@@ -82,10 +82,11 @@ Environment Variables
     ``config.dnn__conv__algo_fwd``) should be defined in their corresponding
     section (e.g. ``[gpuarray]``, ``[dnn.conv]``).
 
-    Multiple configuration files can be specified by separating them with ':'
+    Multiple configuration files can be specified by separating them with ``':'``
     characters (as in ``$PATH``).  Multiple configuration files will be merged,
-    with later (right-most) files taking priority over earlier files in the
-    case that multiple files specify values for a common configuration option.
+    with later (right-most) files taking priority over earlier files, when
+    multiple files specify values for the same configuration option.
+
     For example, to override system-wide settings with personal ones,
     set ``AESARARC=/etc/aesararc:~/.aesararc``. To load configuration files in
     the current working directory, append ``.aesararc`` to the list of configuration
@@ -96,7 +97,7 @@ Config Attributes
 
 The list below describes some of the more common and important flags
 that you might want to use. For the complete list (including documentation),
-import aesara and print the config variable, as in:
+import ``aesara`` and print the config variable, as in:
 
 .. code-block:: bash
 
@@ -116,7 +117,7 @@ import aesara and print the config variable, as in:
 
     This flag's value cannot be modified during the program execution.
 
-    Do not use upper case letters, only lower case even if NVIDIA uses
+    Do not use upper case letters; only lower case, even if NVIDIA uses
     capital letters.
 
 .. attribute:: force_device
@@ -125,13 +126,11 @@ import aesara and print the config variable, as in:
 
     Default: ``False``
 
-    If ``True`` and ``device=gpu*``, we raise an error if we cannot
+    If ``True`` and ``device=gpu*``, Aesara raises an error when it cannot
     use the specified :attr:`device`. If ``True`` and ``device=cpu``,
-    we disable the GPU.  If ``False`` and ``device=gpu*``, and if the
-    specified device cannot be used, we warn and fall back to the CPU.
-
-    This is useful to run Aesara's tests on a computer with a GPU, but
-    without running the GPU tests.
+    Aesara disables the GPU.  If ``False`` and ``device=gpu*``, and when the
+    specified device cannot be used, Aesara emits a warning and falls back to
+    the CPU.
 
     This flag's value cannot be modified during the program execution.
 
@@ -141,14 +140,14 @@ import aesara and print the config variable, as in:
     ``'opencl0:0'``, ``'opencl0:1'``, ...
 
     Initialize the gpu device to use.
-    When its value is ``'cuda*'`` or ``'opencl*'``, the aesara
+    When its value is ``'cuda*'`` or ``'opencl*'``, the Aesara
     flag :attr:`device` must be ``'cpu'``.
     Unlike :attr:`device`, setting this flag to a specific GPU will not
-    try to use this device by default, in particular it will **not** move
-    computations, nor shared variables, to the specified GPU.
+    make Aesara attempt to use the device by default.  More specifically, it
+    will **not** move computations, nor shared variables, to the specified GPU.
 
-    This flag is useful to run GPU-specific tests on a particular GPU, instead
-    of using the default one.
+    This flag can be used to run GPU-specific tests on a particular GPU, instead
+    of the default one.
 
     This flag's value cannot be modified during the program execution.
 
@@ -158,7 +157,7 @@ import aesara and print the config variable, as in:
 
     Default: ``True``
 
-    Print active device at when the GPU device is initialized.
+    Print the active device when the GPU device is initialized.
 
 .. attribute:: floatX
 
@@ -176,8 +175,9 @@ import aesara and print the config variable, as in:
 
     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.
+    This option determines what's done when a ``TensorVariable`` with dtype
+    equal to ``float64`` is created.
+    This can be used to help find upcasts to ``float64`` in user code.
 
 .. attribute:: deterministic
 
@@ -185,12 +185,12 @@ import aesara and print the config variable, as in:
 
     Default: ``'default'``
 
-    If `more`, sometimes we will select some implementation that
-    are more deterministic, but slower. In particular, on the GPU,
-    we will avoid using AtomicAdd. Sometimes we will still use
-    non-deterministic implementaion, e.g. when we do not have a GPU
-    implementation that is deterministic. Also see the dnn.conv.algo*
-    flags to cover more cases.
+    If ``more``, sometimes Aesara will select ``Op`` implementations that
+    are more "deterministic", but slower. In particular, on the GPU,
+    Aesara will avoid using ``AtomicAdd``. Sometimes Aesara will still use
+    non-deterministic implementations, e.g. when there isn't a GPU ``Op``
+    implementation that is deterministic. See the ``dnn.conv.algo*``
+    flags for more cases.
 
 .. attribute:: allow_gc
 
@@ -198,17 +198,17 @@ import aesara and print the config variable, as in:
 
     Default: ``True``
 
-    This sets the default for the use of the Aesara garbage collector
-    for intermediate results. To use less memory, Aesara frees the
-    intermediate results as soon as they are no longer needed.
-    Disabling Aesara garbage collection allows Aesara to reuse buffers
-    for intermediate results between function calls. This speeds up
-    Aesara by no longer spending time reallocating space. This gives
-    significant speed up on functions with many ops that are fast to
-    execute, but this increases Aesara's memory usage.
+    This determines whether or not Aesara's garbage collector is used for
+    intermediate results. To use less memory, Aesara frees the intermediate
+    results as soon as they are no longer needed.  Disabling Aesara's garbage
+    collection allows Aesara to reuse buffers for intermediate results between
+    function calls. This speeds up Aesara by spending less time reallocating
+    space during function evaluation and can provide significant speed-ups for
+    functions with many fast ``Op``s, but it also increases Aesara's memory
+    usage.
 
-.. note:: if :attr:`config.gpuarray__preallocate` is the default value
-    or not disabled (-1), this is not useful anymore on the GPU.
+.. note:: If :attr:`config.gpuarray__preallocate` is the default value
+    or not disabled ``(-1)``, this is not useful anymore on the GPU.
 
 .. attribute:: config.scan__allow_output_prealloc
 
@@ -216,10 +216,9 @@ import aesara and print the config variable, as in:
 
     Default: ``True``
 
-    This enables, or not, an optimization in Scan in which it tries to
-    pre-allocate memory for its outputs. Enabling the optimization can
-    give a significant speed up with Scan at the cost of slightly increased
-    memory usage.
+    This enables, or disables, an optimization in ``Scan`` that tries to
+    pre-allocate memory for its outputs. Enabling the optimization can give a
+    significant speed up at the cost of slightly increased memory usage.
 
 .. attribute:: config.scan__allow_gc
 
@@ -227,11 +226,11 @@ import aesara and print the config variable, as in:
 
     Default: ``False``
 
-    Allow/disallow gc inside of Scan.
+    Allow garbage collection inside of ``Scan`` ``Op``s.
 
     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.
+    ``False``, then Aesara will perform garbage collection during the inner
+    operations of a ``Scan`` after each iterations.
 
 .. attribute:: config.scan__debug
 
@@ -239,7 +238,7 @@ import aesara and print the config variable, as in:
 
     Default: ``False``
 
-    If True, we will print extra scan debug information.
+    If ``True``, Aesara will print extra ``Scan`` debug information.
 
 .. attribute:: cycle_detection
 
@@ -247,13 +246,9 @@ import aesara and print the config variable, as in:
 
     Default: ``regular``
 
-    If :attr:`cycle_detection` is set to ``regular``, most inplaces are allowed,
-    but it is slower. If :attr:`cycle_detection` is set to ``faster``,
-    less inplaces are allowed, but it makes the compilation faster.
-
-    The interaction of which one give the lower peak memory usage is complicated and
-    not predictable, so if you are close to the peak memory usage, trying both
-    could give you a small gain.
+    If :attr:`cycle_detection` is set to ``regular``, most in-place operations are allowed,
+    but graph compilation is slower. If :attr:`cycle_detection` is set to ``faster``,
+    less in-place operations are allowed, but graph compilation is faster.
 
 .. attribute:: check_stack_trace
 
@@ -261,12 +256,12 @@ import aesara and print the config variable, as in:
 
     Default: ``off``
 
-    This is a flag for checking the stack trace during the optimization process.
+    This is a flag for checking the stack trace during graph optimization.
     If :attr:`check_stack_trace` is set to ``off``, no check is performed on the
     stack trace. If :attr:`check_stack_trace` is set to ``log`` or ``warn``, a
     dummy stack trace is inserted that indicates which optimization inserted the
-    variable that had an empty stack trace but, in ``warn`` a warning is also
-    printed.
+    variable that had an empty stack trace, but, when ``warn`` is set, a warning
+    is also printed.
     If :attr:`check_stack_trace` is set to ``raise``, an exception is raised if a
     stack trace is missing.
 
@@ -277,16 +272,16 @@ import aesara and print the config variable, as in:
     Default: ``False``
 
     Enable or disable parallel computation on the CPU with OpenMP.
-    It is the default value used when creating an Op that supports it.
-    It is best to define it in ``.aesararc``
-    or in the environment variable ``AESARA_FLAGS``.
+    It is the default value used by ``Op``s that support OpenMP.
+    It is best to specify this setting in ``.aesararc`` or in the environment
+    variable ``AESARA_FLAGS``.
 
 .. attribute:: openmp_elemwise_minsize
 
     Positive int value, default: 200000.
 
-    This specifies the vectors minimum size for which elemwise `Op`s
-    use OpenMP, if OpenMP is enabled.
+    This specifies the minimum size of a vector for which OpenMP will be used by
+    ``Elemwise`` ``Op``s, when OpenMP is enabled.
 
 .. attribute:: cast_policy
 
@@ -294,28 +289,31 @@ import aesara and print the config variable, as in:
 
     Default: ``'custom'``
 
-    This specifies how data types are implicitly figured out in Aesara, e.g. for
-    constants or in the results of arithmetic operations. The 'custom' value
-    corresponds to a set of custom rules originally used in
-    Aesara (which can be partially customized, see e.g. the in-code help of
-    ``tensor.NumpyAutocaster``), and will be deprecated in the future.
-    The ``'numpy+floatX'`` setting attempts to mimic the numpy casting rules,
-    although it prefers to use float32 numbers instead of float64 when
-    ``config.floatX`` is set to ``'float32'`` and the user uses data that is not
-    explicitly typed as float64 (e.g. regular Python floats).
-    Note that ``'numpy+floatX'`` is not currently behaving exactly as planned (it
-    is a work-in-progress), and thus you should consider it as experimental.
-    At the moment it behaves differently from numpy in the following
-    situations:
-
-    * 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.
+    This specifies how data types are implicitly determined by Aesara during the
+    creation of constants or in the results of arithmetic operations.
+
+    The ``'custom'`` value corresponds to a set of custom rules originally used
+    in Aesara.  These rules can be partially customized (e.g. see the in-code
+    help of ``aesara.scalar.basic.NumpyAutocaster``).  This will be deprecated
+    in the future.
+
+    The ``'numpy+floatX'`` setting attempts to mimic NumPy casting rules,
+    although it prefers to use ``float32` `numbers instead of ``float64`` when
+    ``config.floatX`` is set to ``'float32'`` and the associated data is not
+    explicitly typed as ``float64`` (e.g. regular Python floats).  Note that
+    ``'numpy+floatX'`` is not currently behaving exactly as planned (it is a
+    work-in-progress), and thus it should considered experimental.
+
+    At the moment it behaves differently from NumPy in the following situations:
+
+    * Depending on the value of :attr:`config.int_division`, the resulting dtype
+      of a division of integers with the ``/`` operator may not match
+      that of NumPy.
     * On mixed scalar and array operations, NumPy tries to prevent the scalar
       from upcasting the array's type unless it is of a fundamentally
       different type. Aesara does not attempt to do the same at this point,
-      so you should be careful that scalars may upcast arrays when they
-      would not when using numpy. This behavior should change in the near
+      so users should be careful, since scalars may upcast arrays when they
+      otherwise wouldn't in NumPy. This behavior should change in the near
       future.
 
 .. attribute:: int_division
@@ -325,13 +323,16 @@ import aesara and print the config variable, as in:
     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
-    returned (as in Python 2.X), but this behavior is deprecated. 'floatX'
-    returns a number of type given by ``config.floatX``. 'raise' is the safest
-    choice (and will become default in a future release of Aesara) and raises
-    an error when one tries to do such an operation, enforcing the use of the
-    integer division operator (``//``) (if a float result is intended, either
-    cast one of the arguments to a float, or use ``x.__truediv__(y)``).
+    ``y`` are of integer types (possibly unsigned). ``'int'`` means an integer is
+    returned (as in Python 2.X). This behavior is deprecated.
+
+    ``'floatX'`` returns a number of with the dtype given by ``config.floatX``.
+
+    ``'raise'`` is the safest choice (and will become default in a future
+    release of Aesara).  It raises an error when one tries to perform such an
+    operation, enforcing the use of the integer division operator (``//``). If a
+    float result is desired, either cast one of the arguments to a float, or use
+    ``x.__truediv__(y)``.
 
 .. attribute:: mode
 
@@ -340,8 +341,8 @@ import aesara and print the config variable, as in:
 
     Default: ``'Mode'``
 
-    This sets the default compilation mode for aesara functions. By default the
-    mode Mode is equivalent to FAST_RUN. See Config attribute linker and optimizer.
+    This sets the default compilation mode when compiling Aesara functions. By
+    default the mode ``'Mode'`` is equivalent to ``'FAST_RUN'``.
 
 .. attribute:: profile
 
@@ -349,7 +350,7 @@ import aesara and print the config variable, as in:
 
     Default: ``False``
 
-    Do the vm/cvm linkers profile the execution time of Aesara functions?
+    When ``True``, the VM and CVM linkers profile the execution time of Aesara functions.
 
     See :ref:`tut_profiling` for examples.
 
@@ -359,8 +360,8 @@ import aesara and print the config variable, as in:
 
     Default: ``False``
 
-    Do the vm/cvm linkers profile the memory usage of Aesara functions?
-    It only works when profile=True.
+    When ``True``, the VM and CVM linkers profile the memory usage of Aesara
+    functions.  This only works when ``profile=True``.
 
 .. attribute:: profile_optimizer
 
@@ -368,27 +369,27 @@ import aesara and print the config variable, as in:
 
     Default: ``False``
 
-    Do the vm/cvm linkers profile the optimization phase when compiling an Aesara function?
-    It only works when profile=True.
+    When ``True``, the VM and CVM linkers profile the optimization phase when
+    compiling an Aesara function.  This only works when ``profile=True``.
 
 .. attribute:: config.profiling__n_apply
 
     Positive int value, default: 20.
 
-    The number of Apply nodes to print in the profiler output
+    The number of ``Apply`` nodes to print in the profiler output.
 
 .. attribute:: config.profiling__n_ops
 
     Positive int value, default: 20.
 
-    The number of Ops to print in the profiler output
+    The number of ``Op``s to print in the profiler output.
 
 .. attribute:: config.profiling__min_memory_size
 
     Positive int value, default: 1024.
 
-    For the memory profile, do not print Apply nodes if the size
-    of their outputs (in bytes) is lower than this.
+    During memory profiling, do not print ``Apply`` nodes if the size
+    of their outputs (in bytes) is lower than this value.
 
 .. attribute:: config.profiling__min_peak_memory
 
@@ -396,8 +397,8 @@ import aesara and print the config variable, as in:
 
     Default: ``False``
 
-    Does the memory profile print the min peak memory usage?
-    It only works when profile=True, profile_memory=True
+    When ``True``, print the minimum peak memory usage during memory profiling.
+    This only works when ``profile=True`` and ``profile_memory=True``.
 
 .. attribute:: config.profiling__destination
 
@@ -407,8 +408,8 @@ import aesara and print the config variable, as in:
     Default: ``'stderr'``
 
     Name of the destination file for the profiling output.
-    The profiling output can be either directed to stderr
-    (default), or stdout or an arbitrary file.
+    The profiling output can be directed to stderr (default), stdout, or an
+    arbitrary file.
 
 .. attribute:: config.profiling__debugprint
 
@@ -416,7 +417,7 @@ import aesara and print the config variable, as in:
 
     Default: ``False``
 
-    Do a debugprint of the profiled functions
+    When ``True``, use ``debugprint`` to print the profiled functions.
 
 .. attribute:: config.profiling__ignore_first_call
 
@@ -424,7 +425,7 @@ import aesara and print the config variable, as in:
 
     Default: ``False``
 
-    Do we ignore the first call to an Aesara function while profiling.
+    When ``True``, ignore the first call to an Aesara function while profiling.
 
 .. attribute:: config.lib__amblibm
 
@@ -432,9 +433,9 @@ import aesara and print the config variable, as in:
 
     Default: ``False``
 
-    This makes the compilation use the
-    `amdlibm <https://developer.amd.com/amd-cpu-libraries/amd-math-library-libm/>`__
-    library, which is faster than the standard libm.
+    When ``True``, use the `amdlibm
+    <https://developer.amd.com/amd-cpu-libraries/amd-math-library-libm/>`__
+    library, which is faster than the standard ``libm``.
 
 .. attribute:: config.gpuarray__preallocate
 
@@ -444,14 +445,14 @@ import aesara and print the config variable, as in:
 
     Controls the preallocation of memory with the gpuarray backend.
 
-    The value represents the start size (either in MB or the fraction
+    This value represents the start size (either in MB or the fraction
     of total GPU memory) of the memory pool. If more memory is needed,
     Aesara will try to obtain more, but this can cause memory
     fragmentation.
 
     A negative value will completely disable the allocation cache.
-    This can have a severe impact on performance and so should not be
-    done outside of debugging.
+    This can have a severe impact on performance and should not be
+    used outside of debugging.
 
         * < 0: disabled
         * 0 <= N <= 1: use this fraction of the total GPU memory (clipped to .95 for driver memory).
@@ -459,9 +460,9 @@ import aesara and print the config variable, as in:
 
     .. note::
 
-        This could cause memory fragmentation. So if you have a memory
+        This could cause memory fragmentation, so, if you have a memory
         error while using the cache, try to allocate more memory at
-        the start or disable it.
+        the start, or disable it.
 
     .. note::
 
@@ -479,11 +480,10 @@ import aesara and print the config variable, as in:
 
     Control the stream mode of contexts.
 
-    The sched parameter passed for context creation to pygpu.  With
-    CUDA, using "multi" mean using the parameter
-    cudaDeviceScheduleBlockingSync. This is useful to lower the CPU overhead
-    when waiting for GPU. One user found that it speeds up his other
-    processes that was doing data augmentation.
+    The sched parameter passed for context creation to ``pygpu``.  With
+    CUDA, using ``"multi"`` means using the parameter
+    ``cudaDeviceScheduleBlockingSync``. This is useful to lower the CPU overhead
+    when waiting for a GPU.
 
 
 .. attribute:: config.gpuarray__single_stream
@@ -494,13 +494,9 @@ import aesara and print the config variable, as in:
 
     Control the stream mode of contexts.
 
-    If your computations are mostly lots of small elements, using
+    If your computations consist of mostly small arrays, using
     single-stream will avoid the synchronization overhead and usually
-    be faster.  For larger elements it does not make a difference yet.
-    In the future when true multi-stream is enabled in libgpuarray,
-    this may change.  If you want to make sure to have optimal
-    performance, check both options.
-
+    be faster.  For larger arrays it does not make a difference yet.
 
 .. attribute:: config.gpuarray__cache_path
 
@@ -515,7 +511,7 @@ import aesara and print the config variable, as in:
 
     Default: ``'c|py'``
 
-    When the mode is Mode, it sets the default linker used.
+    When the mode is ``'Mode'``, it sets the default linker used.
     See :ref:`using_modes` for a comparison of the different linkers.
 
 .. attribute:: optimizer
@@ -524,7 +520,7 @@ import aesara and print the config variable, as in:
 
     Default: ``'fast_run'``
 
-    When the mode is Mode, it sets the default optimizer used.
+    When the mode is ``'Mode'``, it sets the default optimizer used.
 
 .. attribute:: on_opt_error
 
@@ -532,10 +528,11 @@ import aesara and print the config variable, as in:
 
     Default: ``'warn'``
 
-    When a crash occurs while trying to apply some optimization, either warn
-    the user and skip this optimization ('warn'), raise the exception
-    ('raise'), fall into the pdb debugger ('pdb') or ignore it ('ignore').
-    We suggest to never use 'ignore' except in tests.
+    When a crash occurs while trying to apply an optimization, either warn the
+    user and skip the optimization (i.e. ``'warn'``), raise the exception
+    (i.e. ``'raise'``), drop into the ``pdb`` debugger (i.e. ``'pdb'``), or
+    ignore it (i.e. ``'ignore'``).
+    We suggest never using ``'ignore'`` except during testing.
 
 .. attribute:: assert_no_cpu_op
 
@@ -543,9 +540,9 @@ import aesara and print the config variable, as in:
 
     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
-    compilation with pdb.
+    If there is a CPU ``Op`` in the computational graph, depending on its value,
+    this flag can either raise a warning, an exception or drop into the frame
+    with ``pdb``.
 
 .. attribute:: on_shape_error
 
@@ -553,9 +550,9 @@ import aesara and print the config variable, as in:
 
     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
-    raise the exception ('raise').
+    When an exception is raised while inferring the shape of an ``Apply``
+    node, either warn the user and use a default value (i.e. ``'warn'``), or
+    raise the exception (i.e. ``'raise'``).
 
 
 .. attribute:: config.warn__ignore_bug_before
@@ -567,16 +564,13 @@ import aesara and print the config variable, as in:
 
     Default: ``'0.9'``
 
-    When we fix an Aesara bug that generated bad results under some
-    circumstances, we also make Aesara raise a warning when it encounters
-    the same circumstances again. This helps to detect if said bug
-    had affected your past experiments, as you only need to run your
-    experiment again with the new version, and you do not have to
-    understand the Aesara internal that triggered the bug. A better
-    way to detect this will be implemented. See this `ticket
-    <http://www.assembla.com/spaces/theano/tickets/514>`__.
+    When we an Aesara bug that generated a bad result is fixed, we also make
+    Aesara raise a warning when it encounters the same circumstances again. This
+    helps users determine whether or not said bug has affected past runs, since
+    one only needs to perform the same runs again with the new version, and one
+    does not have to understand the Aesara internals that triggered the bug.
 
-    This flag allows new users not to get warnings about old bugs, that were
+    This flag lets users ignore warnings about old bugs that were
     fixed before their first checkout of Aesara.
     You can set its value to the first version of Aesara
     that you used (probably 0.3 or higher)
@@ -584,12 +578,7 @@ import aesara and print the config variable, as in:
     ``'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.
-    It is also recommended you put this into your ``.aesararc``, so this setting
-    will always be used.
-
-    This flag's value cannot be modified during the program execution.
+    This flag's value cannot be modified during program execution.
 
 .. attribute:: base_compiledir
 
@@ -598,19 +587,18 @@ import aesara and print the config variable, as in:
 
     This directory stores the platform-dependent compilation directories.
 
-    This flag's value cannot be modified during the program execution.
+    This flag's value cannot be modified during program execution.
 
 .. attribute:: compiledir_format
 
     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
-    compiled modules. To see a list of all available substitution keys,
-    run ``python -c "import aesara; print(aesara.config)"``, and look
-    for compiledir_format.
+    This is a Python format string that specifies the sub-directory of
+    ``config.base_compiledir`` in which platform-dependent compiled modules are
+    stored. To see a list of all available substitution keys, run ``python -c
+    "import aesara; print(aesara.config)"`` and look for ``compiledir_format``.
 
-    This flag's value cannot be modified during the program execution.
+    This flag's value cannot be modified during program execution.
 
 .. attribute:: compiledir
 
@@ -619,15 +607,15 @@ import aesara and print the config variable, as in:
     This directory stores dynamically-compiled modules for a particular
     platform.
 
-    This flag's value cannot be modified during the program execution.
+    This flag's value cannot be modified during program execution.
 
 .. attribute:: config.blas__ldflags
 
     Default: ``'-lblas'``
 
-    Link arguments to link against a (Fortran) level-3 blas
-    implementation.  The default will test if ``'-lblas'`` works. If not,
-    we will disable our C code for BLAS.
+    Link argument to link against a (Fortran) level-3 blas implementation.
+    Aesara will test if ``'-lblas'`` works by default. If not, it will disable C
+    code for BLAS.
 
 .. attribute:: config.experimental__local_alloc_elemwise_assert
 
@@ -635,47 +623,50 @@ import aesara and print the config variable, as in:
 
     Default: ``True``
 
-    When the local_alloc_optimization is applied, add an assert to highlight
-    shape errors.
+    When ``True``, add asserts that highlight shape errors.
+
+    Without such asserts, the underlying optimization could hide errors in user
+    code.  Aesara adds the asserts only if it cannot infer that the shapes are
+    equivalent.  When it can determine equivalence, this optimization does not
+    introduce an assert.
 
-    Without such asserts this optimization could hide errors in the user code.
-    We add the assert only if we can't infer that the shapes are equivalent.
-    As such this optimization does not always introduce an assert in the graph.
-    Removing the assert could speed up execution.
+    Removing these asserts can speed up execution.
 
 .. attribute:: config.dnn__enabled
 
-    String value: ``'auto'``, ``'True'``, ``'False'``
+    String value: ``'auto'``, ``'True'``, ``'False'``, ``'no_check'``
 
     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.
+    `cuDNN <https://developer.nvidia.com/cudnn>`_ when it is available.
+    If cuDNN is unavailable, do not 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'``, neither use cuDNN nor check if it is available.
 
-    If ``'no_check'``, assume present and the version between header and library match (so less compilation at context init)",
+    If ``'no_check'``, assume cuDNN is present and that the versions between the
+    header and library match.
 
 .. attribute:: config.dnn__include_path
 
     Default: ``include`` sub-folder in CUDA root directory, or headers paths defined for the compiler.
 
-    Location of the cudnn header.
+    Location of the cuDNN header.
 
 .. attribute:: config.dnn__library_path
 
-    Default: Library sub-folder (``lib64`` on Linux) in CUDA root directory, or libraries paths defined for the compiler.
+    Default: Library sub-folder (``lib64`` on Linux) in CUDA root directory, or
+    libraries paths defined for the compiler.
 
-    Location of the cudnn library.
+    Location of the cuDNN library.
 
 .. attribute:: config.conv__assert_shape
 
-    If True, AbstractConv* ops will verify that user-provided
-    shapes match the runtime shapes (debugging option,
-    may slow down compilation)
+    If ``True``, ``AbstractConv*`` ``Op``s will verify that user-provided shapes
+    match the run-time shapes. This is a debugging option, and may slow down
+    compilation.
 
 .. attribute:: config.dnn.conv.workmem
 
@@ -724,7 +715,7 @@ import aesara and print the config variable, as in:
 
     Default: ``'none'``
 
-    3d convolution only support ``'none'``, ``'deterministic'``, ``'fft_tiling'``
+    3d convolution only supports ``'none'``, ``'deterministic'``, ``'fft_tiling'``
     ``'guess_once'``, ``'guess_on_shape_change'``, ``'time_once'``,
     ``'time_on_shape_change'``.
 
@@ -756,41 +747,39 @@ import aesara and print the config variable, as in:
     Default: ``''``
 
     Location of the warp-ctc folder. The folder should contain either a build,
-    lib or lib64 subfolder with the shared library (libwarpctc.so), and another
+    lib or lib64 subfolder with the shared library (e.g. ``libwarpctc.so``), and another
     subfolder called include, with the CTC library header.
 
 .. attribute:: config.gcc__cxxflags
 
     Default: ``""``
 
-    Extra parameters to pass to gcc when compiling.  Extra include paths,
+    Extra parameters to pass to ``gcc`` when compiling.  Extra include paths,
     library paths, configuration options, etc.
 
 .. attribute:: cxx
 
-    Default: Full path to g++ if g++ is present. Empty string otherwise.
+    Default: Full path to ``g++`` if ``g++`` is present. Empty string otherwise.
 
     Indicates which C++ compiler to use. If empty, no C++ code is
-    compiled.  Aesara automatically detects whether g++ is present and
-    disables C++ compilation when it is not.  On darwin systems (Mac
-    OS X), it preferably looks for clang++ and uses that if available.
+    compiled.  Aesara automatically detects whether ``g++`` is present and
+    disables C++ compilation when it is not.  On Darwin systems (e.g. Mac
+    OS X), it looks for ``clang++`` and uses that when available.
 
-    We print a warning if we detect that no compiler is present. It is
-    recommended to run with C++ compilation as Aesara will be much
-    slower otherwise.
+    Aesara prints a warning if it detects that no compiler is present.
 
-    This can be any compiler binary (full path or not) but things may
-    break if the interface is not g++-compatible to some degree.
+    This value can point to any compiler binary (full path or not), but things may
+    break if the interface is not ``g++``-compatible to some degree.
 
 .. attribute:: config.optimizer_excluding
 
     Default: ``""``
 
-    A list of optimizer tags that we don't want included in the default Mode.
-    If multiple tags, separate them by ':'.
-    Ex: to remove the elemwise inplace optimizer(slow for big graph),
+    A list of optimizer tags that shouldn't be included in the default ``Mode``.
+    If multiple tags are provided, separate them by ``':'``.
+    For example, to remove the ``Elemwise`` in-place optimizations,
     use the flags: ``optimizer_excluding:inplace_opt``, where
-    inplace_opt is the name of that optimization.
+    ``inplace_opt`` is the name of the optimization group.
 
     This flag's value cannot be modified during the program execution.
 
@@ -798,8 +787,8 @@ import aesara and print the config variable, as in:
 
     Default: ``""``
 
-    A list of optimizer tags that we want included in the default Mode.
-    If multiple tags, separate them by ':'.
+    A list of optimizer tags to be included in the default ``Mode``.
+    If multiple tags are provided, separate them by ``':'``.
 
     This flag's value cannot be modified during the program execution.
 
@@ -807,8 +796,9 @@ import aesara and print the config variable, as in:
 
     Default: ``""``
 
-    A list of optimizer tags that we require for optimizer in the default Mode.
-    If multiple tags, separate them by ':'.
+    A list of optimizer tags that are required for optimization in the default
+    ``Mode``.
+    If multiple tags are provided, separate them by ``':'``.
 
     This flag's value cannot be modified during the program execution.
 
@@ -818,7 +808,7 @@ import aesara and print the config variable, as in:
 
     Default: ``False``
 
-    When True, we print on the stdout the optimization applied.
+    When ``True``, print the optimizations applied to stdout.
 
 .. attribute:: nocleanup
 
@@ -826,24 +816,24 @@ import aesara and print the config variable, as in:
 
     Default: ``False``
 
-    If False, source code files are removed when they are not needed anymore.
-    This means files whose compilation failed are deleted.
-    Set to True to keep those files in order to debug compilation errors.
+    If ``False``, source code files are removed when they are no longer needed.
+    This causes files for which compilation failed to be deleted.
+    Set to ``True`` to keep files for debugging.
 
 .. attribute:: compile
 
     This section contains attributes which influence the compilation of
-    C code for ops.  Due to historical reasons many attributes outside
+    C code for ``Op``s.  Due to historical reasons many attributes outside
     of this section also have an influence over compilation, most
-    notably 'cxx'.  This is not expected to change any time soon.
+    notably ``cxx``.
 
 .. attribute:: config.compile__timeout
 
     Positive int value, default: :attr:`compile__wait` * 24
 
-    Time to wait before an unrefreshed lock is broken and stolen.  This
-    is in place to avoid manual cleanup of locks in case a process
-    crashed and left a lock in place.
+    Time to wait before an un-refreshed lock is broken and stolen (in seconds).
+    This is in place to avoid manual cleanup of locks in case a process crashed
+    and left a lock in place.
 
     The refresh time is automatically set to half the timeout value.
 
@@ -852,22 +842,21 @@ import aesara and print the config variable, as in:
     Positive int value, default: 5
 
     Time to wait between attempts at grabbing the lock if the first
-    attempt is not successful. The actual time will be between
+    attempt is not successful (in seconds). The actual time will be between
     :attr:`compile__wait` and :attr:`compile__wait` * 2 to avoid a
-    crowding effect on lock.
+    crowding effect on the lock.
 
 .. attribute:: DebugMode
 
-    This section contains various attributes configuring the behaviour
-    of mode :class:`~debugmode.DebugMode`. See directly this section
-    for the documentation of more configuration options.
+    This section contains various attributes configuring the behaviour of
+    :class:`~debugmode.DebugMode`.
 
 .. attribute:: config.DebugMode__check_preallocated_output
 
     Default: ``''``
 
     A list of kinds of preallocated memory to use as output buffers for
-    each Op's computations, separated by ``:``. Implemented modes are:
+    each ``Op``'s computations, separated by ``:``. Implemented modes are:
 
     * ``"initial"``: initial storage present in storage map
       (for instance, it can happen in the inner function of Scan),
@@ -893,27 +882,28 @@ import aesara and print the config variable, as in:
 
     Bool value, default: ``True``
 
-    Generate a warning when the destroy_map or view_map tell that an op work
-    inplace, but the op did not reuse the input for its output.
+    Generate a warning when a ``destroy_map`` or ``view_map`` says that an
+    ``Op`` will work inplace, but the ``Op`` does not reuse the input for its
+    output.
 
 .. attribute:: config.NanGuardMode__nan_is_error
 
     Bool value, default: ``True``
 
-    Controls whether NanGuardMode generates an error when it sees a nan.
+    Controls whether ``NanGuardMode`` generates an error when it sees a ``nan``.
 
 .. attribute:: config.NanGuardMode__inf_is_error
 
     Bool value, default: ``True``
 
-    Controls whether NanGuardMode generates an error when it sees an inf.
+    Controls whether ``NanGuardMode`` generates an error when it sees an ``inf``.
 
 .. attribute:: config.NanGuardMode__big_is_error
 
     Bool value, default: ``True``
 
-    Controls whether NanGuardMode generates an error when it sees a
-    big value (>1e10).
+    Controls whether ``NanGuardMode`` generates an error when it sees a
+    big value (i.e. a value greater than ``1e10``).
 
 .. attribute:: compute_test_value
 
@@ -922,45 +912,41 @@ import aesara and print the config variable, as in:
     Default: ``'off'``
 
     Setting this attribute to something other than ``'off'`` activates a
-    debugging mechanism, where Aesara executes the graph on-the-fly, as it is
-    being built. This allows the user to spot errors early on (such as
-    dimension mis-match), **before** optimizations are applied.
+    debugging mechanism, for which Aesara executes the graph on-the-fly, as it
+    is being built. This allows the user to spot errors early on (such as
+    dimension mis-matches) **before** optimizations are applied.
 
-    Aesara 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
-    augmented with test values, by writing to their ``'tag.test_value'``
-    attribute (e.g. ``x.tag.test_value = numpy.random.rand(5, 4)``).
+    Aesara will execute the graph using constants and/or shared variables
+    provided by the user. Purely symbolic variables (e.g. ``x =
+    aesara.tensor.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)``).
 
     When not ``'off'``, the value of this option dictates what happens when
-    an Op's inputs do not provide appropriate test values:
+    an ``Op``'s inputs do not provide appropriate test values:
 
-        - ``'ignore'`` will silently skip the debug mechanism for this Op
-        - ``'warn'`` will raise a UserWarning and skip the debug mechanism for
-          this Op
-        - ``'raise'`` will raise an Exception
+        - ``'ignore'`` will do nothing
+        - ``'warn'`` will raise a ``UserWarning``
+        - ``'raise'`` will raise an exception
 
 .. attribute:: compute_test_value_opt
 
-    As ``compute_test_value``, but it is the value used during Aesara
-    optimization phase. Aesara user's do not need to use this. This is
-    to help debug shape error in Aesara optimization.
+    As ``compute_test_value``, but it is the value used during Aesara's
+    optimization phase.  This is used to help debug shape errors in Aesara's
+    optimizations.
 
 .. attribute:: print_test_value
 
     Bool value, default: ``False``
 
-    If ``'True'``, Aesara will override the ``__str__`` method of its variables
-    to also print the tag.test_value when this is available.
+    If ``'True'``, Aesara will include the test values in a variable's
+    ``__str__`` output.
 
 .. attribute:: reoptimize_unpickled_function
 
     Bool value, default: False
 
-    Aesara users can use the standard python pickle tools to save a compiled
-    aesara function. When pickling, both graph before and after the optimization
-    are saved, including shared variables. When set to ``True``, the graph is
-    reoptimized when being unpickled. Otherwise, skip the graph optimization and
-    use directly the optimized graph.
+    When this option is set to ``True``, a graph is re-optimized when unpickled.
 
 .. attribute:: exception_verbosity
 
@@ -970,7 +956,8 @@ import aesara and print the config variable, as in:
 
     If ``'low'``, the text of exceptions will generally refer to apply nodes
     with short names such as ``'Elemwise{add_no_inplace}'``. If ``'high'``,
-    some exceptions will also refer to apply nodes with long descriptions like:
+    some exceptions will also refer to ``Apply`` nodes with long descriptions
+    like:
 
     ::
 
@@ -983,77 +970,78 @@ import aesara 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
+    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()``
-    function associated to at least one of those Ops.
+    function associated to at least one of those ``Op``s.
 
 .. attribute:: config.cmodule__remove_gxx_opt
 
     Bool value, default: ``False``
 
-    If True, will remove the ``-O*`` parameter passed to g++.
-    This is useful to debug in gdb modules compiled by Aesara.
-    The parameter ``-g`` is passed by default to g++.
+    If ``True``, Aesara will remove the ``-O*`` parameter passed to ``g++``.
+    This is useful for debugging objects compiled by Aesara.  The parameter
+    ``-g`` is also passed by default to ``g++``.
 
 .. attribute:: config.cmodule__compilation_warning
 
     Bool value, default: ``False``
 
-    If True, will print compilation warnings.
+    If ``True``, Aesara will print compilation warnings.
 
 .. attribute:: config.cmodule__preload_cache
 
     Bool value, default: ``False``
 
-    If set to True, will preload the C module cache at import time
+    If set to ``True``, Aesara will preload the C module cache at import time
 
 .. attribute:: config.cmodule__age_thresh_use
 
     Int value, default: ``60 * 60 * 24 * 24``  # 24 days
 
-    In seconds. The time after which a compiled c module won't be
-    reused by Aesara. Automatic deletion of those c module 7 days
-    after that time.
+    The time after which a compiled C module won't be reused by Aesara (in
+    seconds). C modules are automatically deleted 7 days after that time.
 
 .. attribute:: config.cmodule__debug
 
     Bool value, default: ``False``
 
-    If True, define a DEBUG macro (if not exists) for any compiled C code.
+    If ``True``, define a DEBUG macro (if one doesn't already exist) for all
+    compiled C code.
 
 .. attribute:: config.traceback__limit
 
     Int value, default: 8
 
-    The number of user stack level to keep for variables.
+    The number of traceback stack levels to keep for Aesara variable
+    definitions.
 
 .. attribute:: config.traceback__compile_limit
 
     Bool value, default: 0
 
-    The number of user stack level to keep for variables during Aesara
-    compilation. If higher then 0, will make us keep Aesara internal
-    stack trace.
+    The number of traceback stack levels to keep for variables during Aesara
+    compilation. When this value is greater than zero, it will make Aesara keep
+    internal stack traces.
 
 .. attribute:: config.metaopt__verbose
 
     Int value, default: 0
 
-    The verbosity level of the meta-optimizer. 0 for silent.
-    1 to only warn if we cannot meta-optimize some op.
-    2 for full output of separate timings and selected implementation
+    The verbosity level of the meta-optimizer: ``0`` for silent, ``1`` to only
+    warn when Aesara cannot meta-optimize an ``Op``, ``2`` for full output (e.g.
+    timings and the optimizations selected).
 
 
 .. attribute:: config.metaopt__optimizer_excluding
 
     Default: ``""``
 
-    A list of optimizer tags that we don't want included in the Meta-optimizer.
-    If multiple tags, separate them by ':'.
+    A list of optimizer tags that we don't want included in the meta-optimizer.
+    Multiple tags are separate by ``':'``.
 
 .. attribute:: config.metaopt__optimizer_including
 
     Default: ``""``
 
-    A list of optimizer tags that we want included in the Meta-optimizer.
-    If multiple tags, separate them by ':'.
+    A list of optimizer tags to be included during meta-optimization.
+    Multiple tags are separate by ``':'``.