Update docs.

doc/weather-climate.rst

@@ -10,33 +10,38 @@ Weather and climate data
 
 ``xarray`` can leverage metadata that follows the `Climate and Forecast (CF) conventions`_ if present. Examples include automatic labelling of plots with descriptive names and units if proper metadata is present (see :ref:`plotting`) and support for non-standard calendars used in climate science through the ``cftime`` module (see :ref:`CFTimeIndex`). There are also a number of geosciences-focused projects that build on xarray (see :ref:`related-projects`).
 
+.. _Climate and Forecast (CF) conventions: http://cfconventions.org
+
+.. _cf_variables:
+
+Related Variables
+-----------------
+
 Several CF variable attributes contain lists of other variables
 associated with the variable with the attribute.  A few of these are
 now parsed by XArray, with the attribute value popped to encoding on
 read and the variables in that value interpreted as non-dimension
 coordinates:
 
-- `coordinates`
-- `bounds`
-- `grid_mapping`
-- `climatology`
-- `geometry`
-- `node_coordinates`
-- `node_count`
-- `part_node_count`
-- `interior_ring`
-- `cell_measures`
-- `formula_terms`
-
-This decoding is controlled by the `decode_coords` kwarg to
+- ``coordinates``
+- ``bounds``
+- ``grid_mapping``
+- ``climatology``
+- ``geometry``
+- ``node_coordinates``
+- ``node_count``
+- ``part_node_count``
+- ``interior_ring``
+- ``cell_measures``
+- ``formula_terms``
+
+This decoding is controlled by the ``decode_coords`` kwarg to
 :py:func:`open_dataset` and :py:func:`open_mfdataset`.
 
-The CF attribute `ancillary_variables` was not included in the list
+The CF attribute ``ancillary_variables`` was not included in the list
 due to the variables listed there being associated primarily with the
 variable with the attribute, rather than with the dimensions.
 
-.. _Climate and Forecast (CF) conventions: http://cfconventions.org
-
 .. _metpy_accessor:
 
 CF-compliant coordinate variables

doc/whats-new.rst

@@ -33,8 +33,8 @@ Breaking changes
   are now automatically set as coordinate variables. These attributes
   are moved to :py:attr:`DataArray.encoding` from
   :py:attr:`DataArray.attrs`. This behaviour is controlled by the
-  `decode_coords` kwarg to :py:func:`open_dataset` and
-  :py:func:`open_mfdataset`.  The precise list of variables is in
+  ``decode_coords`` kwarg to :py:func:`open_dataset` and
+  :py:func:`open_mfdataset`.  The full list of decoded attributes is in
   :ref:`weather-climate` (:pull:`2844`, :issue:`3689`)
 
 

xarray/backends/api.py

@@ -355,8 +355,8 @@ def open_dataset(
         removed) if they have no corresponding variable and if they are only
         used as the last dimension of character arrays.
     decode_coords : bool, optional
-        If True, decode the 'coordinates' attribute to identify coordinates in
-        the resulting dataset.
+        Use the 'coordinates', 'grid_mapping', 'bounds' and other attributes
+        on variables (or the dataset itself) to identify coordinate variables.
     engine : {"netcdf4", "scipy", "pydap", "h5netcdf", "pynio", "cfgrib", \
         "pseudonetcdf", "zarr"}, optional
         Engine to use when reading files. If not provided, the default engine
@@ -614,8 +614,8 @@ def open_dataarray(
         removed) if they have no corresponding variable and if they are only
         used as the last dimension of character arrays.
     decode_coords : bool, optional
-        If True, decode the 'coordinates' attribute to identify coordinates in
-        the resulting dataset.
+        Use the 'coordinates', 'grid_mapping', 'bounds' and other attributes
+        on variables (or the dataset itself) to identify coordinate variables.
     engine : {"netcdf4", "scipy", "pydap", "h5netcdf", "pynio", "cfgrib"}, \
         optional
         Engine to use when reading files. If not provided, the default engine