Merge pull request #209 from MetOffice/improve_tutorials

Improve tutorials

docs/source/contributing/getting-started.rst

@@ -1,7 +1,5 @@
-.. _working_practices_getting_started:
-
-Getting Started
-===============
+Before you Contribute
+=====================
 
 Before you can get to coding, there are a few steps you need to do.
 
@@ -11,9 +9,10 @@ Getting the code
 Git is a version control software, which makes collaborating on software much
 easier. If you are new to git have a look at the :doc:`git` page to get started.
 
-To get the code onto your computer, you need to clone it with git. Most IDEs
-include the ability to do this in their interfaces, but from the command line it
-can be done with one of the following commands:
+To get the code onto your computer, you need to clone it with git. Most
+:abbr:`IDEs (Integrated Development Environments)` include the ability to do
+this in their interfaces, but from the command line it can be done with one of
+the following commands:
 
 .. code-block:: bash
 

docs/source/getting-started/create-first-recipe.rst

@@ -0,0 +1,204 @@
+Creating your first custom recipe
+=================================
+
+.. Tutorial guiding through how to create a simple custom recipe.
+.. Should include an overview of the recipe format.
+
+In this tutorial we will write a new recipe from scratch.
+
+CSET recipes are written in `YAML 1.2`_, a data format used by many pieces of
+software. Even if you've never seen it before don't worry, as this tutorial
+should cover everything you need to know.
+
+Recipes consist mostly of key-value pairs, which in YAML are denoted with the
+key on the left of a colon, and the value on the right. The value can be a
+string, a number, or even more key-value pairs by indenting them below the key.
+It is important to note that, like in python, indentation is significant in
+YAML. Indentation should be done with two spaces.
+
+.. code-block:: yaml
+
+  # Simple YAML example.
+  key: value
+  key2:
+    key-as-value: value
+
+.. _YAML 1.2: https://en.wikipedia.org/wiki/YAML
+
+Making a new recipe
+-------------------
+
+We will now create a recipe from scratch. This recipe will plot a specific
+timestamp of the example air temperature data.
+
+Start by opening a new file in your favourite text editor, and save it somewhere
+accessible as ``single_timestep_surface_air_temperature_spatial_plot.yaml``.
+
+Recipe Metadata
+---------------
+
+Title
+~~~~~
+
+The first thing we will add to our recipe file is some metadata about the recipe
+itself, starting with its title.
+
+The title is the name of the recipe. It should be sufficiently descriptive so
+you can tell what the recipe does without any further context. It shows up in
+the output page, the plot title, and a few other places.
+
+.. code-block:: yaml
+
+    title: Mean Surface Air Temperature Spatial Plot
+
+Description
+~~~~~~~~~~~
+
+Following the title we have the description. This is a long-form description of
+what the recipe does, considerations around its use, and what science it is
+based on. The description is `Markdown`_, so some formatting can be used where
+helpful, papers can be linked, and so on. A little bit of unusual syntax here is
+``description: |``, with the pipe after the key. This means the indented block
+that follows is a multiline string, so you can have as many lines as you want,
+provided they are all indented with at least two spaces.
+
+.. _Markdown: https://commonmark.org/help/
+
+.. code-block:: yaml
+
+    description: |
+      Extracts and plots the 1.5m air temperature from a file. The temperature
+      is averaged across the time coordinate.
+
+
+Recipe Steps
+------------
+
+Just as in baking you would follow a recipe step-by-step, so does CSET. The
+steps of the recipe are all under the ``steps`` key. Each block prefixed with a
+``-`` (which makes a list in YAML) is a step, and they are run in order from top to bottom.
+
+Each step has an ``operator`` key, which specifies which operator to use. A
+`complete list of operators is in the documentation`_, but for this tutorial we
+will describe them here.
+
+.. _complete list of operators is in the documentation: https://metoffice.github.io/CSET/reference/operators
+
+The first step reads in the model data. This is done with the
+``read.read_cubes`` operator. The first step is special, and receives the path
+to the input data as its implicit input.
+
+.. code-block:: yaml
+
+    steps:
+      - operator: read.read_cubes
+
+Once we have read the data, we need to filter them down to the data we require for our computations.
+``filter.filter_cubes`` is the operator for that. It also ensures that the
+CubeList returned by ``read.read_cubes`` is turned into a
+Cube.
+
+.. code-block:: yaml
+
+    # Filter operator
+      - operator: filters.filter_cubes
+        constraint:
+          operator: constraints.combine_constraints
+          stash_constraint:
+            operator: constraints.generate_stash_constraint
+            stash: m01s03i236
+          cell_methods_constraint:
+            operator: constraints.generate_cell_methods_constraint
+            cell_methods: []
+
+Unlike the ``read.read_cubes`` operator, we have many key-value pairs in this
+step. The other keys in the step are the named arguments that operator takes.
+Each operator implicitly takes its first argument from the previous step, but this
+can be overridden by explicitly providing it.
+
+Note that arguments of operators can themselves be
+operators. This allows nesting operators to use their output as arguments to
+other operators.
+
+
+Next we reduce the dimensionality of the data ahead of plotting. In this
+case we chose the mean of the time coordinate. The ``collapse.collapse`` operator
+allows us to do this, and takes as parameters the coordinate to collapse, and
+the method by which it is done.
+
+.. code-block:: yaml
+
+    # Collapse operator
+      - operator: collapse.collapse
+        coordinate: time
+        method: MEAN
+
+Finally we plot the model data, using the
+``plot.spatial_contour_plot`` operator, and then save the processed data with
+the ``write.write_cube_to_nc`` operator. This finishes up our recipe.
+
+.. TODO: Remove filename argument.
+
+.. code-block:: yaml
+
+    # Plotting and writing operators
+      - operator: plot.spatial_contour_plot
+        filename: CSET_OUTPUT_PATH
+
+      - operator: write.write_cube_to_nc
+        filename: CSET_OUTPUT_PATH
+
+
+Complete Recipe
+---------------
+
+After following this far your recipe should look like this:
+
+.. code-block:: yaml
+
+    title: Mean Surface Air Temperature Spatial Plot
+    description: |
+      Extracts and plots the 1.5m air temperature from a file. The temperature
+      is averaged across the time coordinate.
+
+    steps:
+      - operator: read.read_cubes
+
+      - operator: filters.filter_cubes
+        constraint:
+          operator: constraints.combine_constraints
+          stash_constraint:
+            operator: constraints.generate_stash_constraint
+            stash: m01s03i236
+          cell_methods_constraint:
+            operator: constraints.generate_cell_methods_constraint
+            cell_methods: []
+
+      - operator: collapse.collapse
+        coordinate: time
+        method: MEAN
+
+      - operator: plot.spatial_contour_plot
+        filename: CSET_OUTPUT_PATH
+
+      - operator: write.write_cube_to_nc
+        filename: CSET_OUTPUT_PATH
+
+Running the Recipe
+------------------
+
+We can run this recipe using `the same data`_ as was used for the
+:doc:`run-recipe` tutorial.
+
+.. _the same data: https://github.com/MetOffice/CSET/raw/main/tests/test_data/air_temp.nc
+
+Use ``cset bake`` to run your newly created recipe.
+
+.. code-block:: bash
+
+    cset bake air_temp.nc output/ single_timestep_surface_air_temperature_spatial_plot.yaml
+
+You can investigate the created plot and data file in the specified ``output``
+directory.
+
+You've now successfully written and run a custom CSET recipe.

docs/source/getting-started/index.rst

@@ -1,10 +1,14 @@
 Getting Started
 ===============
 
-This section contains tutorials suitable for someone getting started with CSET.
-By following them you should learn the basics of using CSET.
+This section contains tutorials suitable for getting started with CSET. By
+following them you should learn the basics of using CSET. It is recommended that
+you do them in order.
 
 .. toctree::
     :maxdepth: 2
 
     installation
+    run-recipe
+    visualise-recipe
+    create-first-recipe

docs/source/getting-started/installation.rst

@@ -3,15 +3,45 @@ Installation
 
 .. Tutorial saying how to install CSET. For edge cases should link elsewhere.
 
-The recommended way to install CSET is via conda. It is packaged on
-`conda-forge`_ and can be installed with a simple ``conda create --name=cset
---channel=conda-forge cset``. This will install CSET into its own conda
-environment, which is the recommended way to use it, but it is also possible to
-install it into an existing environment.
+For a user of CSET the recommended way to install CSET is via conda_. It is packaged on
+`conda-forge`_ in the ``cset`` package. The following command will install CSET
+into its own conda environment, which is recommended to avoid possible package
+conflicts.
 
-If you instead want to run a development version that has yet to be released,
-the easiest way is via an editable install. You can learn how to do this in the
-:ref:`working_practices_getting_started` section of the
-:doc:`/contributing/index`.
+.. code-block:: bash
 
+    conda create --name=cset --channel=conda-forge cset
+
+To use CSET, you need to activate the conda environment with the ``conda
+activate`` command.
+
+.. code-block:: bash
+
+    conda activate cset
+
+.. note::
+
+    You will have to rerun the ``conda activate cset`` command whenever you use
+    a new terminal.
+
+Once that is done, CSET should be ready to use. This can be verified by running
+a simple command.
+
+.. code-block:: bash
+
+    cset --version
+
+This command should output the installed version of CSET. This will look
+something like ``CSET v0.4.0``.
+
+You now have CSET installed, so try another tutorial.
+
+.. note::
+
+    This page details installing a released version of CSET. If you instead want
+    to run a development version that has yet to be released, see
+    :doc:`/contributing/getting-started`.
+
+
+.. _conda: https://docs.conda.io/en/latest/
 .. _conda-forge: https://anaconda.org/conda-forge/cset