diff --git a/README.md b/README.md index 7ff3d17c..4b23bac1 100644 --- a/README.md +++ b/README.md @@ -12,11 +12,11 @@ # COSIMA Cookbook This repository is a Cookbook of Recipes 👩🏽‍🍳 👨🏻‍🍳. -A collection of recipes and tutorials for analysing ocean and sea ice model output produced by the [Consortium for Ocean-Sea Ice Modelling in Australia (COSIMA)](http://cosima.org.au/). +A collection of cooking lessons and recipes for analysing ocean and sea ice model output produced by the [Consortium for Ocean-Sea Ice Modelling in Australia (COSIMA)](http://cosima.org.au/). -We explain: a "recipe" here is an example of an analysis of some ocean-sea ice model output or some ocean-related observational datasets. -Each "recipe" comes in a self-contained and well-documented Jupyter notebook. -All the recipes combined form a cookbook 📒! +We explain: a "cooking lesson" here is a tutorial that teaches you something generic (e.g. about plotting or loading data); a "recipe" is an example of an analysis of some ocean-sea ice model output or some ocean-related observational datasets. +Both "cooking lessons" and "recipes" come in self-contained and well-documented Jupyter notebooks. +All the lessons and the recipes combined form a cookbook 📒! Most recipes use output from the [ACCESS-OM2 model](https://doi.org/10.5194/gmd-13-401-2020), while some also use results from configurations of the [Modular Ocean Model 6 (MOM6)](https://github.com/mom-ocean/MOM6) and remote sensing observations. diff --git a/Recipes/Atlantic_IndoPacific_Basin_Overturning_Circulation.ipynb b/Recipes/appetisers-easy/Atlantic_IndoPacific_Basin_Overturning_Circulation.ipynb similarity index 100% rename from Recipes/Atlantic_IndoPacific_Basin_Overturning_Circulation.ipynb rename to Recipes/appetisers-easy/Atlantic_IndoPacific_Basin_Overturning_Circulation.ipynb diff --git a/Recipes/Barotropic_Streamfunction.ipynb b/Recipes/appetisers-easy/Barotropic_Streamfunction.ipynb similarity index 100% rename from Recipes/Barotropic_Streamfunction.ipynb rename to Recipes/appetisers-easy/Barotropic_Streamfunction.ipynb diff --git a/Recipes/Compare_SSH_model_obs.ipynb b/Recipes/appetisers-easy/Compare_SSH_model_obs.ipynb similarity index 100% rename from Recipes/Compare_SSH_model_obs.ipynb rename to Recipes/appetisers-easy/Compare_SSH_model_obs.ipynb diff --git a/Recipes/Compare_SST_SSS_TemperatureSalinity_to_WOA13.ipynb b/Recipes/appetisers-easy/Compare_SST_SSS_TemperatureSalinity_to_WOA13.ipynb similarity index 100% rename from Recipes/Compare_SST_SSS_TemperatureSalinity_to_WOA13.ipynb rename to Recipes/appetisers-easy/Compare_SST_SSS_TemperatureSalinity_to_WOA13.ipynb diff --git a/Recipes/Hovmoller_Temperature_Depth.ipynb b/Recipes/appetisers-easy/Hovmoller_Temperature_Depth.ipynb similarity index 100% rename from Recipes/Hovmoller_Temperature_Depth.ipynb rename to Recipes/appetisers-easy/Hovmoller_Temperature_Depth.ipynb diff --git a/Recipes/Meridional_Overturning_Circulation.ipynb b/Recipes/appetisers-easy/Meridional_Overturning_Circulation.ipynb similarity index 100% rename from Recipes/Meridional_Overturning_Circulation.ipynb rename to Recipes/appetisers-easy/Meridional_Overturning_Circulation.ipynb diff --git a/Recipes/Model_Resolution_Comparison.ipynb b/Recipes/appetisers-easy/Model_Resolution_Comparison.ipynb similarity index 100% rename from Recipes/Model_Resolution_Comparison.ipynb rename to Recipes/appetisers-easy/Model_Resolution_Comparison.ipynb diff --git a/Recipes/Querying_Scalar_Quantities_and_Annually_Averaged_Timeseries.ipynb b/Recipes/appetisers-easy/Querying_Scalar_Quantities_and_Annually_Averaged_Timeseries.ipynb similarity index 100% rename from Recipes/Querying_Scalar_Quantities_and_Annually_Averaged_Timeseries.ipynb rename to Recipes/appetisers-easy/Querying_Scalar_Quantities_and_Annually_Averaged_Timeseries.ipynb diff --git a/Recipes/Relative_Vorticity.ipynb b/Recipes/appetisers-easy/Relative_Vorticity.ipynb similarity index 100% rename from Recipes/Relative_Vorticity.ipynb rename to Recipes/appetisers-easy/Relative_Vorticity.ipynb diff --git a/Recipes/Transport_Through_Straits.ipynb b/Recipes/appetisers-easy/Transport_Through_Straits.ipynb similarity index 100% rename from Recipes/Transport_Through_Straits.ipynb rename to Recipes/appetisers-easy/Transport_Through_Straits.ipynb diff --git a/Recipes/True_Zonal_Mean.ipynb b/Recipes/appetisers-easy/True_Zonal_Mean.ipynb similarity index 100% rename from Recipes/True_Zonal_Mean.ipynb rename to Recipes/appetisers-easy/True_Zonal_Mean.ipynb diff --git a/Recipes/regional-mom6-forced-by-access-om2.ipynb b/Recipes/local-dishes-regional/regional-mom6-forced-by-access-om2.ipynb similarity index 100% rename from Recipes/regional-mom6-forced-by-access-om2.ipynb rename to Recipes/local-dishes-regional/regional-mom6-forced-by-access-om2.ipynb diff --git a/Recipes/Along-slope-velocities.ipynb b/Recipes/mains-advanced/Along-slope-velocities.ipynb similarity index 100% rename from Recipes/Along-slope-velocities.ipynb rename to Recipes/mains-advanced/Along-slope-velocities.ipynb diff --git a/Recipes/Along_Isobath_Average.ipynb b/Recipes/mains-advanced/Along_Isobath_Average.ipynb similarity index 100% rename from Recipes/Along_Isobath_Average.ipynb rename to Recipes/mains-advanced/Along_Isobath_Average.ipynb diff --git a/Recipes/Cross-contour_transport.ipynb b/Recipes/mains-advanced/Cross-contour_transport.ipynb similarity index 100% rename from Recipes/Cross-contour_transport.ipynb rename to Recipes/mains-advanced/Cross-contour_transport.ipynb diff --git a/Recipes/Cross-slope_section.ipynb b/Recipes/mains-advanced/Cross-slope_section.ipynb similarity index 100% rename from Recipes/Cross-slope_section.ipynb rename to Recipes/mains-advanced/Cross-slope_section.ipynb diff --git a/Recipes/Eddy-Mean_Kinetic_Energy_Decomposition.ipynb b/Recipes/mains-advanced/Eddy-Mean_Kinetic_Energy_Decomposition.ipynb similarity index 100% rename from Recipes/Eddy-Mean_Kinetic_Energy_Decomposition.ipynb rename to Recipes/mains-advanced/Eddy-Mean_Kinetic_Energy_Decomposition.ipynb diff --git a/Recipes/Equatorial_thermal_and_zonal_velocity_structure.ipynb b/Recipes/mains-advanced/Equatorial_thermal_and_zonal_velocity_structure.ipynb similarity index 100% rename from Recipes/Equatorial_thermal_and_zonal_velocity_structure.ipynb rename to Recipes/mains-advanced/Equatorial_thermal_and_zonal_velocity_structure.ipynb diff --git a/Recipes/Extract_Variables_at_Ocean_Bottom.ipynb b/Recipes/mains-advanced/Extract_Variables_at_Ocean_Bottom.ipynb similarity index 100% rename from Recipes/Extract_Variables_at_Ocean_Bottom.ipynb rename to Recipes/mains-advanced/Extract_Variables_at_Ocean_Bottom.ipynb diff --git a/Recipes/Geostrophic_Velocities_from_Sea_Level.ipynb b/Recipes/mains-advanced/Geostrophic_Velocities_from_Sea_Level.ipynb similarity index 100% rename from Recipes/Geostrophic_Velocities_from_Sea_Level.ipynb rename to Recipes/mains-advanced/Geostrophic_Velocities_from_Sea_Level.ipynb diff --git a/Recipes/Horizontal_Regridding.ipynb b/Recipes/mains-advanced/Horizontal_Regridding.ipynb similarity index 100% rename from Recipes/Horizontal_Regridding.ipynb rename to Recipes/mains-advanced/Horizontal_Regridding.ipynb diff --git a/Recipes/Meridional_heat_transport.ipynb b/Recipes/mains-advanced/Meridional_heat_transport.ipynb similarity index 100% rename from Recipes/Meridional_heat_transport.ipynb rename to Recipes/mains-advanced/Meridional_heat_transport.ipynb diff --git a/Recipes/Nearest_Neighbour_Distance.ipynb b/Recipes/mains-advanced/Nearest_Neighbour_Distance.ipynb similarity index 100% rename from Recipes/Nearest_Neighbour_Distance.ipynb rename to Recipes/mains-advanced/Nearest_Neighbour_Distance.ipynb diff --git a/Recipes/Neutral_density.ipynb b/Recipes/mains-advanced/Neutral_density.ipynb similarity index 100% rename from Recipes/Neutral_density.ipynb rename to Recipes/mains-advanced/Neutral_density.ipynb diff --git a/Recipes/Particle_tracking_with_Parcels.ipynb b/Recipes/mains-advanced/Particle_tracking_with_Parcels.ipynb similarity index 100% rename from Recipes/Particle_tracking_with_Parcels.ipynb rename to Recipes/mains-advanced/Particle_tracking_with_Parcels.ipynb diff --git a/Recipes/Sea_Ice_Area_Concentration_Volume_with_Obs.ipynb b/Recipes/mains-advanced/Sea_Ice_Area_Concentration_Volume_with_Obs.ipynb similarity index 100% rename from Recipes/Sea_Ice_Area_Concentration_Volume_with_Obs.ipynb rename to Recipes/mains-advanced/Sea_Ice_Area_Concentration_Volume_with_Obs.ipynb diff --git a/Recipes/Sea_Ice_Coordinates.ipynb b/Recipes/mains-advanced/Sea_Ice_Coordinates.ipynb similarity index 100% rename from Recipes/Sea_Ice_Coordinates.ipynb rename to Recipes/mains-advanced/Sea_Ice_Coordinates.ipynb diff --git a/Recipes/Sea_Ice_Seasonality_Statistics.ipynb b/Recipes/mains-advanced/Sea_Ice_Seasonality_Statistics.ipynb similarity index 100% rename from Recipes/Sea_Ice_Seasonality_Statistics.ipynb rename to Recipes/mains-advanced/Sea_Ice_Seasonality_Statistics.ipynb diff --git a/Recipes/Surface_Water_Mass_Transformation.ipynb b/Recipes/mains-advanced/Surface_Water_Mass_Transformation.ipynb similarity index 100% rename from Recipes/Surface_Water_Mass_Transformation.ipynb rename to Recipes/mains-advanced/Surface_Water_Mass_Transformation.ipynb diff --git a/Recipes/Temperature_Salinity_Diagram.ipynb b/Recipes/mains-advanced/Temperature_Salinity_Diagram.ipynb similarity index 100% rename from Recipes/Temperature_Salinity_Diagram.ipynb rename to Recipes/mains-advanced/Temperature_Salinity_Diagram.ipynb diff --git a/Recipes/Transformation_from_Depth_to_Potential_Density.ipynb b/Recipes/mains-advanced/Transformation_from_Depth_to_Potential_Density.ipynb similarity index 100% rename from Recipes/Transformation_from_Depth_to_Potential_Density.ipynb rename to Recipes/mains-advanced/Transformation_from_Depth_to_Potential_Density.ipynb diff --git a/docs/conf.py b/docs/conf.py index 992710cd..ca907282 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -55,6 +55,10 @@ # a list of builtin themes. # # html_theme = 'default' +html_theme_options = { + "sidebar_collapse": False, + "sidebar_includehidden": False, +} # Add any paths that contain custom static files (such as style sheets) here, # relative to this directory. They are copied after the builtin static files, diff --git a/docs/guidelines.rst b/docs/guidelines.rst index d83b4aae..51071080 100644 --- a/docs/guidelines.rst +++ b/docs/guidelines.rst @@ -44,8 +44,7 @@ format for the other entries already in there. Images in notebooks ------------------- -If including external images (i.e. not plots generated in the code) in +If including external images (i.e., not plots generated in the code) in notebooks, place them in the ``images/`` directory next to the notebook. Use the syntax ``![image caption](images/image.png)`` to include the image in the notebook. - diff --git a/docs/index.rst b/docs/index.rst index 82d0f12e..a45861b7 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -3,6 +3,7 @@ You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive. + COSIMA Cookbook =============== @@ -16,20 +17,18 @@ All the recipes combined form a cookbook 📒! Happy cooking! 😉 🥙 🍱 🍲 -To get started have a look at the tutorials_ and then browse through the -available recipes_ to find something the better suits your 'taste' (i.e., your needs)! -The `COSIMA Cookbook tutorial`_ is perhaps the best place to start. +To get started you should first take the :doc:`Cooking Lessons 101 ` (i.e., our Tutorials). +After you've gone through them and feel comfortable, browse through the +available :doc:`recipes/index` (i.e., examples) to find something the better suits your 'taste' (i.e., your needs)! -.. _tutorials: tutorials.html -.. _recipes: recipes.html -.. _COSIMA Cookbook tutorial: https://cosima-recipes.readthedocs.io/en/latest/Tutorials/COSIMA_CookBook_Tutorial.html +The :doc:`COSIMA Cookbook tutorial ` is perhaps the best place to start. .. toctree:: - :maxdepth: 1 + :maxdepth: 2 :caption: Contents: tutorials - recipes + recipes/index guidelines contributing GitHub Repository diff --git a/docs/recipes.rst b/docs/recipes.rst deleted file mode 100644 index f115aefc..00000000 --- a/docs/recipes.rst +++ /dev/null @@ -1,10 +0,0 @@ -Recipes -======= - -.. nbgallery:: - :caption: Recipes - :name: recipe-gallery - :glob: - :hidden: - - Recipes/* diff --git a/docs/recipes/appetisers.rst b/docs/recipes/appetisers.rst new file mode 100644 index 00000000..5f9d35a4 --- /dev/null +++ b/docs/recipes/appetisers.rst @@ -0,0 +1,9 @@ +Appetisers (easy) +================= + +.. nbgallery:: + :name: recipe-gallery-appetisers + :glob: + :hidden: + + ../Recipes/appetisers-easy/* diff --git a/docs/recipes/index.rst b/docs/recipes/index.rst new file mode 100644 index 00000000..3c32c24e --- /dev/null +++ b/docs/recipes/index.rst @@ -0,0 +1,13 @@ +Recipes +======= + +The recipes are split into :doc:`appetisers` (i.e., easier/simpler recipes -- a good place +to start after you've been through the :doc:`../tutorials`), :doc:`mains` (i.e. elaborate/advanced recipes) +and :doc:`local-dishes` (i.e. recipes for regional configurations). + +.. toctree:: + :maxdepth: 1 + + appetisers + mains + local-dishes diff --git a/docs/recipes/local-dishes.rst b/docs/recipes/local-dishes.rst new file mode 100644 index 00000000..296cb644 --- /dev/null +++ b/docs/recipes/local-dishes.rst @@ -0,0 +1,9 @@ +Local dishes (Regional configurations) +====================================== + +.. nbgallery:: + :name: recipe-gallery-regional + :glob: + :hidden: + + ../Recipes/local-dishes-regional/* diff --git a/docs/recipes/mains.rst b/docs/recipes/mains.rst new file mode 100644 index 00000000..b8434367 --- /dev/null +++ b/docs/recipes/mains.rst @@ -0,0 +1,9 @@ +Main dishes (advanced) +====================== + +.. nbgallery:: + :name: recipe-gallery-mains + :glob: + :hidden: + + ../Recipes/mains-advanced/* diff --git a/docs/tutorials.rst b/docs/tutorials.rst index 71c60f97..cf463418 100644 --- a/docs/tutorials.rst +++ b/docs/tutorials.rst @@ -1,8 +1,7 @@ -Tutorials -========= +Cooking lessons 101 (Tutorials) +=============================== .. nbgallery:: - :caption: Tutorials :name: tutorial-gallery :glob: :hidden: