More improvements.

Author: pp-mo

docs/changelog_fragments/68.feat.rst

@@ -3,4 +3,4 @@ The :class:`ncdata.NcData` objects can be indexed with the ``[]`` operation, or
 specifed dimensions with the :meth:`~ncdata.NcData.slicer` method.
 This is based on the new :meth:`~ncdata.utils.index_by_dimensions()` utility method
 and :class:`~ncdata.utils.Slicer` class.
-See: :ref:`indexing_overview`
+See: :ref:`utils_indexing`

docs/details/developer_notes.rst

@@ -46,7 +46,7 @@ For a full docs-build:
 
 .. note::
 
-    * the above is just for *local testing*, when required.
+    * the above is just for **local testing**, when required.
     * For PRs (and releases), we also provide *automatic* builds on GitHub,
       via ReadTheDocs_.
 
@@ -56,9 +56,9 @@ Release actions
 
 #. Update the :ref:`change-log page <change_log>` in the details section
 
-    #. ensure all major changes + PRs are referenced in the :ref:`change_notes` section.
+    #. start with ``$ towncrier build``
 
-       * The starting point for this is now just : ``$ towncrier build``.
+    #. ensure all major changes + PRs are referenced in the :ref:`change_notes` section.
 
     #. update the "latest version" stated in the :ref:`development_status` section
 

docs/userdocs/user_guide/common_operations.rst

@@ -126,16 +126,16 @@ Equality Testing
 We implement equality operations ``==`` / ``!=`` for all the core data objects.
 
 .. warning::
-    The equality testing actually calls the :func:`ncdata.utils.dataset_differences` and
-    :func:`ncdata.utils.variable_differences` utility functions.
+    Equality testing for :class:`~ncdata.NcData` and :class:`~ncdata.NcVariable` actually
+    calls the :func:`ncdata.utils.dataset_differences` and
+    :func:`ncdata.utils.variable_differences` utilities.
 
     This can be very costly if it needs to compare large data arrays.
 
-If you need to avoid comparing large (and possibly lazy) arrays then you should use the
+If you need to avoid comparing large (and possibly lazy) arrays then you can use the
 :func:`ncdata.utils.dataset_differences` and
-:func:`ncdata.utils.variable_differences` utility functions directly.
-These enable you to use the provided tolerance options, such as ignoring differences in
-data content, or accepting that attributes are present in a different order.
+:func:`ncdata.utils.variable_differences` utility functions directly instead.
+These provide a ``check_var_data=False`` option, to ignore differences in data content.
 
 See: :ref:`utils_equality`
 

docs/userdocs/user_guide/data_objects.rst

@@ -186,7 +186,9 @@ However, for most operations on attributes, it is much easier to use the ``.aval
 property instead.  This accesses *the same attributes*, but in the form of a simple
 "name: value" dictionary.
 
-Thus for example, to fetch an attribute you would usually write just :
+Get attribute value
+^^^^^^^^^^^^^^^^^^^
+For example, to fetch an attribute you would usually write just :
 
 .. testsetup::
 
@@ -205,23 +207,15 @@ and **not** :
 
 .. doctest:: python
 
-    >>> # WRONG: this reads an NcAttribute, not its value
+    >>> # WRONG: this get the NcAttribute object, not its value
     >>> unit = dataset.variables["x"].attributes["units"]
 
-or:
-
-.. doctest:: python
-
-    >>> # WRONG: this gets NcAttribute.value as a character array, not a string
+    >>> # WRONG: this returns a character array, not a string
     >>> unit = dataset.variables["x"].attributes["units"].value
 
-or even (which is at least correct):
-
-.. doctest:: python
-
-    >>> unit = dataset.variables["x"].attributes["units"].as_python_value()
-
 
+Set attribute value
+^^^^^^^^^^^^^^^^^^^
 Likewise, to **set** a value, you would normally just
 
 .. doctest:: python
@@ -236,9 +230,11 @@ and **not**
     >>> dataset.variables["x"].attributes["units"].value = "K"
 
 
-Note also, that as the ``.avals`` is a dictionary, you can use standard dictionary
-methods such as ``update`` and ``get`` to perform other operations in a relatively
-natural, Pythonic way.
+``.avals`` as a dictionary
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+Note also, that as ``.avals`` is a dictionary, you can use standard dictionary
+methods such as ``pop``, ``update`` and ``get`` to perform other operations in a
+relatively natural, Pythonic way.
 
 .. doctest:: python
 
@@ -247,6 +243,12 @@ natural, Pythonic way.
 
     >>> dataset.attributes.update({"experiment": "A407", "expt_run": 704})
 
+.. note::
+    The new ``.avals`` property effectively replaces the old
+    :meth:`~ncdata.NcData.get_attrval` and :meth:`~ncdata.NcData.set_attrval` methods,
+    which are now deprecated and will eventually be removed.
+
+
 .. _data-constructors:
 
 Core Object Constructors

docs/userdocs/user_guide/utilities.rst

@@ -18,7 +18,7 @@ Dataset Equality Testing
 ------------------------
 The functions :func:`~ncdata.utils.dataset_differences` and
 :func:`~ncdata.utils.variable_differences` produce a list of messages detailing all the
-ways in which two datasets are different.
+ways in which two datasets or variables are different.
 
 For Example:
 ^^^^^^^^^^^^
@@ -51,19 +51,22 @@ For Example:
     Dataset "x" dimension has different "unlimited" status : False != True
     Dataset variable "vx" shapes differ : (5,) != (2,)
 
-.. note::
-   To compare isolated variables, the subsidiary routine
-   :func:`~ncdata.utils.variable_differences` is also provided.
+For a short-form test that two things are the same, you can just check that the
+results ``== []``.
+
+By default, these functions compare **everything** about the two arguments.
+However, they also have multiple keywords which allow certain *types* of differences to
+be ignored, E.G. ``check_dims_order=False``, ``check_var_data=False``.
 
 .. note::
     The ``==`` and ``!=`` operations on  :class:`ncdata.NcData` and
-    :class:`ncdata.NcVariable` simply call these utility functions to see if there are
-    any differences.
+    :class:`ncdata.NcVariable` use these utility functions to check for differences.
 
     .. warning::
-        As they lack a keyword interface, these operations have no tolerance options
-        and check absolutely everything.  This includes full data-array comparisons,
-        which could be very costly in time or space if data arrays are large.
+        As they lack a keyword interface, these operations provide no tolerance options,
+        so they always check absolutely everything.  Especially, they perform **full
+        data-array comparisons**, which can have very high performance costs if data
+        arrays are large.
 
 .. _utils_indexing: