clean up the documentation (#177)

* update the docstring of `DataArray.pint.quantify`

* same for `Dataset.pint.quantify`

* link to the proper section on pint's string formatting

* add markers to the link texts of the extlinks

* fix some links

* remove the explicit mention of ipython_genutils

* unpin sphinx

Author: keewis

docs/conf.py

@@ -75,8 +75,8 @@
 
 # extlinks
 extlinks = {
-    "issue": (f"{github_url}/issues/%s", "GH"),
-    "pull": (f"{github_url}/pull/%s", "PR"),
+    "issue": (f"{github_url}/issues/%s", "GH%s"),
+    "pull": (f"{github_url}/pull/%s", "PR%s"),
 }
 
 # autosummary

docs/contributing.rst

@@ -14,5 +14,5 @@ In order to keep code consistent, we use
 
 - `Black <https://black.readthedocs.io/en/stable/>`_ for standardized code formatting
 - `blackdoc <https://blackdoc.readthedocs.io/en/stable/>`_ for standardized code formatting in documentation
-- `Flake8 <http://flake8.pycqa.org/en/latest/>`_ for general code quality
-- `isort <https://github.com/timothycrosley/isort>`_ for standardized order in imports. See also `flake8-isort <https://github.com/gforcada/flake8-isort>`_.
+- `Flake8 <https://flake8.pycqa.org/en/latest/>`_ for general code quality
+- `isort <https://github.com/PyCQA/isort>`_ for standardized order in imports. See also `flake8-isort <https://github.com/gforcada/flake8-isort>`_.

docs/creation.rst

@@ -130,6 +130,6 @@ This will get the string representation of a :py:class:`pint.Unit` instance and
 attach it as a ``units`` attribute. The data of the variable will now be
 whatever `pint`_ wrapped.
 
-.. _pint: https://pint.readthedocs.org/en/stable
-.. _xarray: https://xarray.pydata.org/en/stable
+.. _pint: https://pint.readthedocs.io/en/stable/
+.. _xarray: https://docs.xarray.dev/en/stable/
 .. _units in indexes: https://github.com/pydata/xarray/issues/1603

docs/requirements.txt

@@ -3,8 +3,7 @@ xarray>=0.16.0
 pooch
 netCDF4
 cf-xarray>=0.6
-sphinx<4
-ipython_genutils  # remove once there's a new `nbconvert` release
+sphinx
 sphinx_rtd_theme
 ipython
 ipykernel

docs/whats-new.rst

@@ -35,10 +35,10 @@ What's new
 -----------------
 - rewrite :py:meth:`Dataset.pint.quantify` and :py:meth:`DataArray.pint.quantify`, to
   use pint's ``UnitRegistry.parse_units`` instead of ``UnitRegistry.parse_expression``
-  (:pull:`40`)
+  (:issue:`40`)
   By `Tom Nicholas <https://github.com/TomNicholas>`_.
 - ensure the variables which causes the error is explicit if an error occurs in
-  :py:meth:`Dataset.pint.quantify` and other methods (:pull:`43`, :pull:`91`)
+  :py:meth:`Dataset.pint.quantify` and other methods (:pull:`43`, :issue:`91`)
   By `Tom Nicholas <https://github.com/TomNicholas>`_ and `Justus Magin <https://github.com/keewis>`_.
 - refactor the internal conversion functions (:pull:`56`)
   By `Justus Magin <https://github.com/keewis>`_.

pint_xarray/accessors.py

@@ -245,7 +245,7 @@ def quantify(self, units=_default, unit_registry=None, **unit_kwargs):
         parsed by the given unit registry. If no units are specified then the
         units will be parsed from the `'units'` entry of the DataArray's
         `.attrs`. Will raise a ValueError if the DataArray already contains a
-        unit-aware array.
+        unit-aware array with a different unit.
 
         .. note::
             Be aware that unless you're using ``dask`` this will load
@@ -310,6 +310,18 @@ def quantify(self, units=_default, unit_registry=None, **unit_kwargs):
         <xarray.DataArray (wavelength: 2)>
         array([0.4, 0.9])
         Dimensions without coordinates: wavelength
+
+        Quantify with the same unit:
+
+        >>> q = da.pint.quantify()
+        >>> q
+        <xarray.DataArray (wavelength: 2)>
+        <Quantity([0.4 0.9], 'hertz')>
+        Dimensions without coordinates: wavelength
+        >>> q.pint.quantify("Hz")
+        <xarray.DataArray (wavelength: 2)>
+        <Quantity([0.4 0.9], 'hertz')>
+        Dimensions without coordinates: wavelength
         """
         if units is None or isinstance(units, (str, pint.Unit)):
             if self.da.name in unit_kwargs:
@@ -397,7 +409,8 @@ def dequantify(self, format=None):
 
         See Also
         --------
-        https://pint.readthedocs.io/en/stable/tutorial.html#string-formatting
+        :doc:`pint:formatting`
+            pint's string formatting guide
 
         Examples
         --------
@@ -958,7 +971,7 @@ def quantify(self, units=_default, unit_registry=None, **unit_kwargs):
         units are specified then the units will be parsed from the
         ``"units"`` entry of the Dataset variable's ``.attrs``. Will
         raise a ValueError if any of the variables already contain a
-        unit-aware array.
+        unit-aware array with a different unit.
 
         .. note::
             Be aware that unless you're using ``dask`` this will load
@@ -1035,6 +1048,28 @@ def quantify(self, units=_default, unit_registry=None, **unit_kwargs):
         Data variables:
             a        (x) int64 0 3 2
             b        (x) int64 5 -2 1
+
+        Quantify with the same unit:
+
+        >>> q = ds.pint.quantify()
+        >>> q
+        <xarray.Dataset>
+        Dimensions:  (x: 3)
+        Coordinates:
+          * x        (x) int64 0 1 2
+            u        (x) int64 [s] -1 0 1
+        Data variables:
+            a        (x) int64 [m] 0 3 2
+            b        (x) int64 5 -2 1
+        >>> q.pint.quantify({"a": "m"})
+        <xarray.Dataset>
+        Dimensions:  (x: 3)
+        Coordinates:
+          * x        (x) int64 0 1 2
+            u        (x) int64 [s] -1 0 1
+        Data variables:
+            a        (x) int64 [m] 0 3 2
+            b        (x) int64 5 -2 1
         """
         units = either_dict_or_kwargs(units, unit_kwargs, "quantify")
         registry = get_registry(unit_registry, units, conversion.extract_units(self.ds))
@@ -1100,8 +1135,8 @@ def dequantify(self, format=None):
         Parameters
         ----------
         format : str, default: None
-            The format specification (as accepted by pint) used for the string
-            representations. If ``None``, the registry's default
+            The format specification (as accepted by pint's unit formatter) used for the
+            string representations. If ``None``, the registry's default
             (:py:attr:`pint.UnitRegistry.default_format`) is used instead.
 
         Returns
@@ -1112,7 +1147,8 @@ def dequantify(self, format=None):
 
         See Also
         --------
-        https://pint.readthedocs.io/en/stable/tutorial.html#string-formatting
+        :doc:`pint:formatting`
+            pint's string formatting guide
 
         Examples
         --------