m300977: Added example_notbooks.rst to list notebooks in a reasonable order...

m300977: Added example_notbooks.rst to list notebooks in a reasonable order for documentation. Linking the notebooks into the documentation does not work so far.

doc/conf.py

@@ -20,7 +20,7 @@ import os
 import sys
 # sys.path.insert(0, os.path.abspath('.'))
 sys.path.insert(0, os.path.abspath('../..'))  # Source code dir relative to this file
-
+ 
 
 # -- General configuration ------------------------------------------------
 
@@ -36,8 +36,8 @@ extensions = [
     'sphinx.ext.todo',
     'sphinx.ext.imgmath',
 #    'sphinx.ext.autosummary',
-#    'nbsphinx',
-#    "sphinx_copybutton",
+    'nbsphinx',
+    "sphinx_copybutton",
 #    "IPython.sphinxext.ipython_directive",
 #    "IPython.sphinxext.ipython_console_highlighting",
 ]
@@ -95,7 +95,7 @@ todo_include_todos = True
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-html_theme = 'alabaster'
+html_theme = 'pydata_sphinx_theme'
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the

doc/example_notebooks.rst

+=================
+Example notebooks
+=================
+
+In this section, we introduce examples of using pyicon. In ``Introduction`` we cover some basics of python and pyicon. Then, we have three subsections ``Atmosphere``, ``Ocean``, and ``Ocean-Atmosphere`` covering the usage of pyicon specifically for the ocean and the atmosphere. In the section ``Plotting`` we show how to manage axes and grids. Finally, in the section ``View``, we cover a pyicon specific, pyicon view, that aims to reproduce some ncview-like plotting options. A great overview of pyicon is the notebook ``Basic plotting of ICON data``, and we recommend going through this notebook. 
+
+
+Introductory notebooks
+======================
+
+In this section, you can find introduction notebooks. If you are already experienced in python, we advise you to start with ``Basic plotting of ICON data``. 
+For beginners, we offer a basic python introduction ``Welcome to a short introduction to python``. If you are already experienced in python and only new to pyicon, you can start with ``Starter example for pyicon``. 
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Contents:
+
+   notebooks/python_introduction.ipynb
+   notebooks/examp_easyms2022.ipynb
+   notebooks/examp_intro_plot_options.ipynb
+   notebooks/examp_intro_start.ipynb
+   notebooks/examp_intro_start_xr.ipynb
+   notebooks/test_pyicon_section.ipynb
+
+
+Atmosphere
+==========
+
+Here you can find notebooks of examples where pyicon is used for atmosphere.
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Contents:
+
+
+   notebooks/examp_atm_2d_scalars.ipynb
+   notebooks/examp_atm_converting_omega_to_w.ipynb
+   notebooks/examp_atm_equation_of_state.ipynb
+   notebooks/examp_atm_geopotential_height.ipynb
+   notebooks/examp_atm_plot_zonally_averaged_data.ipynb
+   notebooks/examp_atm_plotting_era_data.ipynb
+   notebooks/examp_atm_wind_stress.ipynb
+   notebooks/examp_atm_wind_stress_curl.ipynb
+
+Ocean
+=====
+
+Here you can find notebooks of examples where pyicon is used for ocean.
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Contents:
+
+   notebooks/examp_intro_start.ipynb
+   notebooks/examp_intro_start_xr.ipynb
+   notebooks/examp_oce_biases.ipynb
+   notebooks/examp_oce_density_and_velocity_gradients.ipynb
+   notebooks/examp_oce_geostrophic_velocities.ipynb
+   notebooks/examp_oce_reconstructions.ipynb
+   notebooks/examp_oce_timeseries.ipynb
+   notebooks/examp_oce_transports.ipynb
+   notebooks/examp_oce_uvw_from_mass_flux.ipynb
+   notebooks/examp_oce_vert_grad_unequal_spacing.ipynb
+   notebooks/examp_oce_zstar.ipynb
+
+Ocean Atmposphere
+=================
+
+ 
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Contents:
+
+   notebooks/examp_oceatm_crop_domain.ipynb
+   notebooks/examp_oceatm_save_netcdf.ipynb
+   notebooks/examp_oceatm_time_averaging_with_dask.ipynb
+
+Plotting
+========
+
+The following notebooks are the examples of plotting with pyicon, mainly covering how to modify axes and grids.  
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Contents:
+
+   notebooks/examp_plotting_arrange_axes.ipynb
+   notebooks/examp_plotting_dual_and_primal_grid.ipynb
+   notebooks/examp_plotting_map_projections.ipynb
+   notebooks/examp_plotting_split_axes_vertically.ipynb
+
+View
+====
+In this section we cover pyicon view that aims to reproduce some ncview like plotting options. This allows loading an ICON data set and click through the time or depth axes. All variables within the file can be depicted, color limits can be set and the plot can be manipulated e.g. by adding Rectangles.
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Contents:
+
+   notebooks/pyicon_view_cdo_remapped.ipynb
+   notebooks/pyicon_view_nextgems.ipynb
+   notebooks/pyicon_view_nextgems_xr.ipynb 
+   notebooks/pyicon_view_nextgems_xr_intake.ipynb
+   notebooks/pyicon_view_nextgems_xr_intake_minimum_example.ipynb
+   notebooks/pyicon_view_r2b6.ipynb
+   notebooks/pyicon_view_r2b8.ipynb
+   notebooks/pyicon_view_smt.ipynb
+   

doc/index.rst

@@ -15,12 +15,13 @@ Pyicon is developed by the Max Planck Institute for Meterology and the Universit
 Pyicon is hosted here: `<https://gitlab.dkrz.de/m300602/pyicon/>`_
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 1 
    :caption: Contents:
 
    installation
    quickstart
    mistral
+   example_notebooks
    documentation
    quickplots
    view