Better documentation of options (#6723)

Author: dcherian

doc/user-guide/index.rst

@@ -24,4 +24,5 @@ examples that describe many common tasks that you can accomplish with xarray.
    io
    dask
    plotting
+   options
    duckarrays

doc/user-guide/options.rst

@@ -0,0 +1,36 @@
+.. currentmodule:: xarray
+
+.. _options:
+
+Configuration
+=============
+
+Xarray offers a small number of configuration options through :py:func:`set_options`. With these, you can
+
+1. Control the ``repr``:
+
+   - ``display_expand_attrs``
+   - ``display_expand_coords``
+   - ``display_expand_data``
+   - ``display_expand_data_vars``
+   - ``display_max_rows``
+   - ``display_style``
+
+2. Control behaviour during operations: ``arithmetic_join``, ``keep_attrs``, ``use_bottleneck``.
+3. Control colormaps for plots:``cmap_divergent``, ``cmap_sequential``.
+4. Aspects of file reading: ``file_cache_maxsize``, ``warn_on_unclosed_files``.
+
+
+You can set these options either globally
+
+::
+
+  xr.set_options(arithmetic_join="exact")
+
+or locally as a context manager:
+
+::
+
+   with xr.set_options(arithmetic_join="exact"):
+       # do operation here
+       pass

xarray/core/options.py

@@ -141,7 +141,18 @@ class set_options:
     Parameters
     ----------
     arithmetic_join : {"inner", "outer", "left", "right", "exact"}, default: "inner"
-        DataArray/Dataset alignment in binary operations.
+        DataArray/Dataset alignment in binary operations:
+
+        - "outer": use the union of object indexes
+        - "inner": use the intersection of object indexes
+        - "left": use indexes from the first object with each dimension
+        - "right": use indexes from the last object with each dimension
+        - "exact": instead of aligning, raise `ValueError` when indexes to be
+          aligned are not equal
+        - "override": if indexes are of same size, rewrite indexes to be
+          those of the first object with that dimension. Indexes for the same
+          dimension must have the same size in all objects.
+
     cmap_divergent : str or matplotlib.colors.Colormap, default: "RdBu_r"
         Colormap to use for divergent data plots. If string, must be
         matplotlib built-in colormap. Can also be a Colormap object