update documentation

docs/building/Makefile

@@ -14,7 +14,7 @@ all: $(TARGETS)
 
 
 clean::
-	rm -fr *.zarr *.txt
+	rm -fr *.zarr
 
 .SUFFIXES: .zarr .yaml .txt
 .PRECIOUS: %.zarr

docs/building/building2.txt

@@ -0,0 +1,32 @@
+┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈
+📦 Path          : dataset.zarr
+🔢 Format version: 0.20.0
+
+📅 Start      : 2024-01-01 00:00
+📅 End        : 2024-01-01 18:00
+⏰ Frequency  : 6h
+🚫 Missing    : 0
+🌎 Resolution : 1.0
+🌎 Field shape: [181, 360]
+
+📐 Shape      : 4 × 11 × 1 × 65,160 (10.9 MiB)
+💽 Size       : 5.7 MiB (5,995,688)
+📁 Files      : 34
+
+   Index │ Variable │         Min │         Max │        Mean │       Stdev
+   ──────┼──────────┼─────────────┼─────────────┼─────────────┼────────────
+       0 │ 10u      │    -24.3116 │       25.79 │   0.0595319 │      5.5856
+       1 │ 10v      │    -21.2397 │      21.851 │   -0.270924 │     4.23947
+       2 │ 2t       │     214.979 │     319.111 │     277.775 │     19.9318
+       3 │ lsm      │           0 │           1 │    0.335152 │    0.464236
+       4 │ msl      │     95708.5 │      104284 │      100867 │     1452.67
+       5 │ q_100    │ 8.95676e-07 │ 5.19827e-06 │ 2.78594e-06 │ 5.39734e-07
+       6 │ q_50     │ 1.89449e-06 │ 3.41429e-06 │ 3.00331e-06 │ 1.11219e-07
+       7 │ t_100    │      186.33 │      233.74 │     209.958 │     12.4899
+       8 │ t_50     │     191.921 │     241.239 │     213.774 │     12.3492
+       9 │ z_100    │      146865 │      163937 │      157791 │     4962.71
+      10 │ z_50     │      186876 │      204383 │      199752 │     4158.18
+   ──────┴──────────┴─────────────┴─────────────┴─────────────┴────────────
+🔋 Dataset ready, last update 19 seconds ago.
+📊 Statistics ready.
+

docs/building/building2.yaml

@@ -0,0 +1,16 @@
+dates:
+  start: 2024-01-01T00:00:00Z
+  end: 2024-01-01T18:00:00Z
+  frequency: 6h
+
+input:
+  join:
+  - mars:
+      param: [2t, msl, 10u, 10v, lsm]
+      levtype: sfc
+      grid: [1, 1]
+  - mars:
+      param: [q, t, z]
+      levtype: pl
+      level: [50, 100]
+      grid: [1, 1]

docs/building/introduction.rst

@@ -78,23 +78,44 @@ operations can be combined to build complex datasets.
  Getting started
 *****************
 
-The simplest recipe file must contain a ``dates`` section and an ``input`` section. The latter
-must contain a `source` In that case, the source is ``mars``
+First example
+=============
+
+The simplest recipe file must contain a ``dates`` section and an
+``input`` section. The latter must contain a `source` In that case, the
+source is ``mars``
 
 .. literalinclude:: building1.yaml
    :language: yaml
 
-To create the dataser, run the following command:
+To create the dataset, run the following command:
 
-.. code-block:: console
+.. code:: console
 
    $ anemoi-datasets create recipe.yaml dataset.zarr
 
-Once the build is complete, you can inspect the dataset using the following command:
+Once the build is complete, you can inspect the dataset using the
+following command:
 
-.. code-block:: console
+.. code:: console
 
    $ anemoi-datasets inspect dataset.zarr
 
 .. literalinclude:: building1.txt
    :language: console
+
+Adding a second source
+======================
+
+To add a second source, you need to use the ``join`` operation. In that
+example, we add pressure level variables to the previous example:
+
+.. literalinclude:: building2.yaml
+   :language: yaml
+
+This will build the following dataset:
+
+.. literalinclude:: building2.txt
+   :language: console
+
+.. note:: Please note that the pressure levels parameters are named `param_level`. This is the default behaviour. See :ref:`remapping_option` for more information.

docs/building/naming_variables.rst

@@ -10,9 +10,10 @@
 
 The rename filter is used to rename variables in a dataset.
 
+.. _remapping_option:
+
 *************************
- remapping output option
+ remapping  option
 *************************
 
-The remapping output option is used to specify the output dataset for
-the remapping operation.
+TODO.