update doc

Author: b8raoult

docs/building/operations.rst

@@ -33,9 +33,9 @@ each providing a different period.
  pipe
 ******
 
-The pipe is the process of transforming fields using filters. The first
-step of a pipe is typically a source, a join or another pipe. The
-following steps are filters.
+The pipe is the process of transforming fields using :ref:`filters
+<filters>`. The first step of a pipe is typically a source, a join or
+another pipe. The following steps are filters.
 
 .. literalinclude:: pipe.yaml
    :language: yaml

docs/using/grids.rst

@@ -8,10 +8,37 @@
  thinning
 **********
 
+You can thin a dataset by specifying the ``thinning`` parameter in the
+``open_dataset`` function. The ``thinning`` parameter depends on the
+``method`` select. The default (and only) method is "every-nth", which
+will mask out all but every Nth point, with N specified by the
+``thinning`` parameter.
+
 .. code:: python
 
-   open_dataset(dataset, thinning=..., method="every-nth")
+   ds = open_dataset(dataset, thinning=N, method="every-nth")
+
+Please note that the thinning will apply to all dimension of the fields.
+So for 2D fields, the thinning will apply to both the latitude and
+longitude dimensions. For 1D fields, such as reduced Gaussian grids, the
+thinning will apply to the only dimension.
 
 ******
  area
 ******
+
+You can crop a dataset to a specific area by specifying the area in the
+``open_dataset`` function. The area is specified as a list of four
+numbers in the order ``(north, west, south, east)``. For example, to
+crop a dataset to the area
+
+.. code:: python
+
+   ds = open_dataset(dataset, area=(60, 10, 50, 20))
+
+Alternatively, you can specific another dataset as the area. In this
+case, the bounding box of the dataset will be used.
+
+.. code:: python
+
+   ds = open_dataset(dataset1, area=dataset2)

docs/using/other.rst

@@ -4,28 +4,35 @@
  Other operations
 ##################
 
-.. warning:: The operations described in this section are do not check that their inputs are compatible.
+.. warning::
 
+   The operations described in this section are do not check that their
+   inputs are compatible.
 
 *****
  zip
 *****
 
-The `zip` operation is used to combine multiple datasets into a single dataset.
+The `zip` operation is used to combine multiple datasets into a single
+dataset.
 
 .. code:: python
 
    ds = open_dataset(zip=[dataset1, dataset2, ...])
 
-   # This will return tuples
+This operation is similar to the Python's :py:func:`zip` function, but
+it returns tuples of the selected indices instead of the values:
 
-   print(ds[0])
-
-   print(ds[3, 4])
+.. code:: python
 
+   print(ds[0])
+   # (dataset1[0], dataset2[0], ...)
 
+   print(ds[0, 1])
+   # (dataset1[0, 1], dataset2[0, 1], ...)
 
-This operation is identical to the Python's :py:func:`zip` function.
+   print(ds[0:2])
+   # (dataset1[0:2], dataset2[0:2], ...)
 
 *******
  chain
@@ -35,19 +42,23 @@ This operation is identical to the Python's :py:func:`zip` function.
 
    ds = open_dataset(chain=[dataset1, dataset2, ...])
 
+The `chain` operation is used to combine multiple datasets into a single
+dataset. The datasets are combined by concatenating the data arrays
+along the first dimension (dates). This is similar to the :ref:`concat`
+operation, but no check are done to see if the datasets are compatible,
+this means that the shape of the arrays returned when iterating or
+indexing may be different.
 
-The `chain` operation is used to combine multiple datasets into a single dataset.
-The datasets are combined by concatenating the data arrays along the first dimension (dates).
-This is similar to the :ref:`concat` operation, but no check are done to see if the datasets are compatible,
-this means that the shape of the arrays returned when iterating or indexing may be different.
+This operation is identical to the Python's :py:func:`itertools.chain`
+function.
 
-This operation is identical to the Python's :py:func:`itertools.chain` function.
-
-
-********
+*********
  shuffle
-********
+*********
 
 .. code:: python
 
    ds = open_dataset(dataset, shuffle=True)
+
+The `shuffle` operation is used to shuffle the data in the dataset along
+the first dimension (dates).

docs/using/subsetting.rst

@@ -38,4 +38,5 @@ You can change the frequency of the dataset by passing a string with the
 
 .. code:: python
 
-   ds = open_dataset("aifs-ea-an-oper-0001-mars-o96-1979-2022-1h-v2", frequency="6h")
+   ds = open_dataset("aifs-ea-an-oper-0001-mars-o96-1979-2022-1h-v2",
+      frequency="6h")