Skip to content

Commit a335615

Browse files
keewiskeewis
authored
docs update (#20)
* extend the docs a bit * include a terminology page * add xarray and pint to intersphinx * use the new term to make the docstrings less ambiguous * update the docs requirements * set up a mapping of type aliases * avoid the use of :param: as that will duplicate parameters when using "x, y : str" styled parameter documentation * expand the index page * fix a sidebar caption * don't use a custom link text for pint.Unit * move the type information from the definition to the description * add ipython to the used extensions * add terminology to the toctree * add blackdoc to pre-commit * add a rough draft of the quantify howto-guide * add netcdf4 to the requirements * enable the type preprocessor * use ipython prompts in the directives * rephrase the reference to the github repository * add a howto-guide for converting units * clean up the sphinx configuration a bit * configure extlinks * add an item to the changelog * add some text to the empty examples section * update the install instructions * avoid recommending a workflow that would break CF compliance * rename the changelog to whats-new
1 parent 4347a32 commit a335615

12 files changed

+277
-18
lines changed

‎.pre-commit-config.yaml

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,10 @@ repos:
1010
rev: stable
1111
hooks:
1212
- id: black
13+
- repo: https://github.com/keewis/blackdoc
14+
rev: stable
15+
hooks:
16+
- id: blackdoc
1317
- repo: https://gitlab.com/pycqa/flake8
1418
rev: 3.8.1
1519
hooks:

‎docs/conf.py

Lines changed: 32 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -29,6 +29,7 @@
2929
project = "pint-xarray"
3030
author = f"{project} developers"
3131
copyright = f"{year}, {author}"
32+
github_url = "https://github.com/xarray-contrib/pint-xarray"
3233

3334

3435
# -- General configuration ---------------------------------------------------
@@ -38,10 +39,13 @@
3839
# ones.
3940
extensions = [
4041
"sphinx.ext.intersphinx",
42+
"sphinx.ext.extlinks",
4143
"sphinx.ext.autosummary",
4244
"sphinx.ext.autodoc",
4345
"sphinx.ext.napoleon",
4446
"sphinx_autosummary_accessors",
47+
"IPython.sphinxext.ipython_directive",
48+
"IPython.sphinxext.ipython_console_highlighting",
4549
]
4650

4751
# Add any paths that contain templates here, relative to this directory.
@@ -68,13 +72,38 @@
6872

6973
# -- Extension configuration -------------------------------------------------
7074

75+
# extlinks
76+
extlinks = {
77+
"issue": (f"{github_url}/issues/%s", "GH"),
78+
"pull": (f"{github_url}/pull/%s", "PR"),
79+
}
80+
81+
# autosummary
7182
autosummary_generate = True
83+
84+
# autodoc
7285
autodoc_typehints = "none"
7386

74-
napoleon_use_param = True
87+
# napoleon
88+
napoleon_use_param = False
7589
napoleon_use_rtype = True
7690

91+
napoleon_preprocess_types = True
92+
napoleon_type_aliases = {
93+
"dict-like": ":term:`dict-like <mapping>`",
94+
"mapping": ":term:`mapping`",
95+
"hashable": ":term:`hashable`",
96+
# xarray
97+
"Dataset": "~xarray.Dataset",
98+
"DataArray": "~xarray.DataArray",
99+
# pint / pint-xarray
100+
"unit-like": ":term:`unit-like`",
101+
}
102+
77103
# -- Options for intersphinx extension ---------------------------------------
78104

79-
# Example configuration for intersphinx: refer to the Python standard library.
80-
intersphinx_mapping = {"https://docs.python.org/3/": None}
105+
intersphinx_mapping = {
106+
"python": ("https://docs.python.org/3/", None),
107+
"xarray": ("https://xarray.pydata.org/en/stable", None),
108+
"pint": ("https://pint.readthedocs.io/en/stable", None),
109+
}

‎docs/contributing.rst

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
Contributing
2+
============
3+
``pint-xarray`` is developed on `github <https://github.com/xarray-contrib/pint-xarray>`_.
4+
5+
Linters / Autoformatters
6+
------------------------
7+
In order to keep code consistent, we use
8+
9+
- `Black <https://black.readthedocs.io/en/stable/>`_ for standardized code formatting
10+
- `blackdoc <https://blackdoc.readthedocs.io/en/stable/>`_ for standardized code formatting in documentation
11+
- `Flake8 <http://flake8.pycqa.org/en/latest/>`_ for general code quality
12+
- `isort <https://github.com/timothycrosley/isort>`_ for standardized order in imports. See also `flake8-isort <https://github.com/gforcada/flake8-isort>`_.

‎docs/conversion.rst

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
.. currentmodule:: xarray
2+
3+
Converting units
4+
================
5+
.. ipython:: python
6+
:suppress:
7+
8+
import xarray as xr
9+
10+
When working with :py:class:`Dataset` or :py:class:`DataArray` objects with
11+
units, we frequently might want to convert the units. Suppose we have:
12+
13+
.. ipython::
14+
15+
In [1]: ds = xr.Dataset(
16+
...: {"a": ("x", [4, 8, 12, 16])}, coords={"u": ("x", [10, 20, 30, 40])}
17+
...: ).pint.quantify({"a": "m", "u": "s"})
18+
...: ds
19+
20+
In [2]: da = ds.a
21+
...: da
22+
23+
To convert the data to different units, we can use the
24+
:py:meth:`Dataset.pint.to` and :py:meth:`DataArray.pint.to` methods:
25+
26+
.. ipython::
27+
28+
In [3]: ds.pint.to(a="feet", u="ks")
29+
30+
In [4]: da.pint.to({da.name: "nautical_mile", "u": "ms"})

‎docs/creation.rst

Lines changed: 97 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,97 @@
1+
.. currentmodule:: xarray
2+
3+
Creating and saving objects with units
4+
======================================
5+
6+
Attaching units
7+
---------------
8+
.. ipython:: python
9+
:suppress:
10+
11+
import xarray as xr
12+
13+
Usually, when loading data from disk we get a :py:class:`Dataset` or
14+
:py:class:`DataArray` with units in attributes:
15+
16+
.. ipython::
17+
18+
In [1]: ds = xr.Dataset(
19+
...: {
20+
...: "a": (("lon", "lat"), [[11.84, 3.12, 9.7], [7.8, 9.3, 14.72]]),
21+
...: "b": (("lon", "lat"), [[13, 2, 7], [5, 4, 9]], {"units": "m"}),
22+
...: },
23+
...: coords={"lat": [10, 20, 30], "lon": [74, 76]},
24+
...: )
25+
...: ds
26+
27+
In [2]: da = ds.b
28+
...: da
29+
30+
In order to get :py:class:`pint.Quantity` instances, we can use the
31+
:py:meth:`Dataset.pint.quantify` or :py:meth:`DataArray.pint.quantify` methods:
32+
33+
.. ipython::
34+
35+
In [3]: ds.pint.quantify()
36+
37+
We can also override the units of a variable:
38+
39+
.. ipython::
40+
41+
In [4]: ds.pint.quantify(b="km")
42+
43+
In [5]: da.pint.quantify({"b": "degree"})
44+
45+
Overriding works, even if there is no ``units`` attribute, so we could use this
46+
to attach units to a normal :py:class:`Dataset`:
47+
48+
.. ipython::
49+
50+
In [6]: temporary_ds = xr.Dataset({"a": ("x", [0, 5, 10])}, coords={"x": [1, 2, 3]})
51+
...: temporary_ds.pint.quantify({"a": "m"})
52+
53+
Of course, we could use :py:class:`pint.Unit` instances instead of strings to
54+
specify units, too.
55+
56+
If we wanted to change the units of the data of a :py:class:`DataArray`, we
57+
could do so using the :py:attr:`DataArray.name` attribute:
58+
59+
.. ipython::
60+
61+
In [7]: da.pint.quantify({da.name: "J", "lat": "degree", "lon": "degree"})
62+
63+
However, `xarray`_ currently doesn't support `units in indexes`_, so the new units were set
64+
as attributes. To really observe the changes the ``quantify`` methods make, we
65+
have to first swap the dimensions:
66+
67+
.. ipython::
68+
69+
In [8]: ds_with_units = ds.swap_dims({"lon": "x", "lat": "y"}).pint.quantify(
70+
...: {"lat": "degree", "lon": "degree"}
71+
...: )
72+
...: ds_with_units
73+
74+
In [9]: da_with_units = da.swap_dims({"lon": "x", "lat": "y"}).pint.quantify(
75+
...: {"lat": "degree", "lon": "degree"}
76+
...: )
77+
...: da_with_units
78+
79+
Saving with units
80+
-----------------
81+
In order to not lose the units when saving to disk, we first have to call the
82+
:py:meth:`Dataset.pint.dequantify` and :py:meth:`DataArray.pint.dequantify`
83+
methods:
84+
85+
.. ipython::
86+
87+
In [10]: ds_with_units.pint.dequantify()
88+
89+
In [11]: da_with_units.pint.dequantify()
90+
91+
This will get the string representation of a :py:class:`pint.Unit` instance and
92+
attach it as a ``units`` attribute. The data of the variable will now be
93+
whatever `pint`_ wrapped.
94+
95+
.. _pint: https://pint.readthedocs.org/en/stable
96+
.. _xarray: https://xarray.pydata.org/en/stable
97+
.. _units in indexes: https://github.com/pydata/xarray/issues/1603

‎docs/examples.rst

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
Examples
2+
========
3+
There are no examples yet.

‎docs/index.rst

Lines changed: 48 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,53 @@
1-
.. accessors documentation master file, created by
2-
sphinx-quickstart on Thu Jul 2 01:49:50 2020.
3-
You can adapt this file completely to your liking, but it should at least
4-
contain the root `toctree` directive.
1+
pint-xarray
2+
===========
3+
A convenience wrapper for using `pint`_ in `xarray`_ objects.
54

6-
Welcome to accessors's documentation!
7-
=====================================
5+
.. _pint: https://pint.readthedocs.io/en/stable
6+
.. _xarray: https://xarray.pydata.org/en/stable
7+
8+
Documentation
9+
-------------
10+
11+
**Getting Started**:
12+
13+
- :doc:`installation`
14+
- :doc:`examples`
15+
16+
.. toctree::
17+
:maxdepth: 1
18+
:caption: Getting Started
19+
:hidden:
20+
21+
installation
22+
examples
23+
24+
**User Guide**:
25+
26+
- :doc:`terminology`
27+
- :doc:`creation`
28+
- :doc:`conversion`
29+
30+
.. toctree::
31+
:maxdepth: 1
32+
:caption: User Guide
33+
:hidden:
34+
35+
terminology
36+
creation
37+
conversion
38+
39+
40+
**Help & Reference**:
41+
42+
- :doc:`whats-new`
43+
- :doc:`api`
44+
- :doc:`contributing`
845

946
.. toctree::
10-
:maxdepth: 2
11-
:caption: Contents:
47+
:maxdepth: 1
48+
:caption: Help & Reference
49+
:hidden:
1250

51+
whats-new
1352
api
53+
contributing

‎docs/installation.rst

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
Installation
2+
------------
3+
Install from ``conda-forge``:
4+
5+
.. code:: sh
6+
7+
conda install -c conda-forge pint-xarray
8+
9+
or from ``PyPI``:
10+
11+
.. code:: sh
12+
13+
python -m pip install pint-xarray
14+
15+
or from source, either directly from github:
16+
17+
.. code:: sh
18+
19+
python -m pip install git+https://github.com/xarray-contrib/pint-xarray
20+
21+
or from a local copy:
22+
23+
.. code:: sh
24+
25+
git clone https://github.com/xarray-contrib/pint-xarray
26+
python -m pip install ./pint-xarray

‎docs/requirements.txt

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,8 @@
1-
pint>=0.13
2-
xarray>=0.15.1
3-
sphinx>=3.0
1+
pint>=0.14
2+
xarray>=0.16.0
3+
netCDF4
4+
sphinx>=3.2
45
sphinx_rtd_theme
6+
ipython
57
nbsphinx
68
sphinx-autosummary-accessors

‎docs/terminology.rst

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
Terminology
2+
===========
3+
4+
.. glossary::
5+
6+
unit-like
7+
A `pint`_ unit definition, as accepted by :py:class:`pint.Unit`.
8+
May be either a :py:class:`str` or a :py:class:`pint.Unit` instance.
9+
10+
.. _pint: https://pint.readthedocs.io/en/stable

‎docs/whats-new.rst

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
What's new
2+
==========
3+
4+
0.1 (*unreleased*)
5+
------------------
6+
- add documentation (:pull:`20`)

‎pint_xarray/accessors.py

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -148,7 +148,7 @@ def quantify(
148148
149149
Parameters
150150
----------
151-
units : pint.Unit or str or mapping of hashable to pint.Unit or str, optional
151+
units : unit-like or mapping of hashable to unit-like, optional
152152
Physical units to use for this DataArray. If a str or
153153
pint.Unit, will be used as the DataArray's units. If a
154154
dict-like, it should map a variable name to the desired
@@ -275,7 +275,7 @@ def to(self, units=None, **unit_kwargs):
275275
276276
Parameters
277277
----------
278-
units : str or pint.Unit or mapping of hashable to str or pint.Unit, optional
278+
units : unit-like or mapping of hashable to unit-like, optional
279279
The units to convert to. If a unit name or ``pint.Unit``
280280
object, convert the DataArray's data. If a dict-like, it
281281
has to map a variable name to a unit name or ``pint.Unit``
@@ -440,7 +440,7 @@ def quantify(
440440
441441
Parameters
442442
----------
443-
units : mapping of hashable to pint.Unit or str, optional
443+
units : mapping of hashable to unit-like, optional
444444
Physical units to use for particular DataArrays in this
445445
Dataset. It should map variable names to units (unit names
446446
or ``pint.Unit`` objects). If not provided, will try to
@@ -532,7 +532,7 @@ def to(self, units=None, **unit_kwargs):
532532
533533
Parameters
534534
----------
535-
units : mapping of hashable to str or pint.Unit, optional
535+
units : mapping of hashable to unit-like, optional
536536
Maps variable names to the unit to convert to.
537537
**unit_kwargs
538538
The kwargs form of ``units``. Can only be used for

0 commit comments

Comments
 (0)