Merge pull request #1610 from OceanParcels/v/update-notebooks

Documentation improvements (update import statements, include scripts)

Author: VeckoTheGecko

.flake8

@@ -10,3 +10,5 @@ ignore =
     E501,
     # ‘from module import *’ used; unable to detect undefined names
     F403,
+    # incompatability with Black
+    E203

.git-blame-ignore-revs

@@ -3,3 +3,6 @@
 
 # whitespace fixes
 e99e0d170a7dc128031b82ea00cdf9e9a0164b03
+
+# Run black on examples
+cbf96c4e1f58fa6348695d7553900ba3f7c3383b

.pre-commit-config.yaml

@@ -13,10 +13,11 @@ repos:
     rev: "7.1.0"
     hooks:
       - id: flake8
-  - repo: https://github.com/pycqa/pydocstyle
-    rev: 6.3.0 # pick a git hash / tag to point to
+  - repo: https://github.com/psf/black-pre-commit-mirror
+    rev: 24.4.2
     hooks:
-      - id: pydocstyle
+      - id: black
+        files: docs/examples
   - repo: https://github.com/nbQA-dev/nbQA
     rev: 1.8.5
     hooks:
@@ -28,7 +29,7 @@ repos:
     hooks:
       - id: isort
         name: isort (python)
-  - repo: https://github.com/pre-commit/mirrors-prettier
-    rev: "v4.0.0-alpha.8"
+  - repo: https://github.com/biomejs/pre-commit
+    rev: v0.4.0
     hooks:
-      - id: prettier
+      - id: biome-format

.readthedocs.yaml

@@ -9,6 +9,7 @@ build:
 
 sphinx:
   configuration: docs/conf.py
+  builder: dirhtml
 
 conda:
   environment: environment.yml

docs/conf.py

@@ -317,7 +317,11 @@ def linkcode_resolve(domain, info):
 # html_use_smartypants = True
 
 # Custom sidebar templates, maps document names to template names.
-# html_sidebars = {}
+
+html_sidebars = {
+    "**": ["sidebar-nav-bs"],
+    "documentation/additional_examples": []
+}
 
 # Additional templates that should be rendered to pages, maps page names to
 # template names.

docs/contributing.rst

@@ -41,7 +41,7 @@ Your first contribution
 There are many ways that you can contribute to Parcels. You can:
 
 - Participate in discussion about Parcels, either through the `issues <https://github.com/OceanParcels/parcels/issues>`_ or `discussions <https://github.com/OceanParcels/parcels/discussions>`_ tab
-- Suggest improvements to `tutorials <documentation.rst>`_
+- Suggest improvements to `tutorials <documentation/index.rst>`_
 - Suggest improvements to `documentation <index.rst>`_
 - Write code (fix bugs, implement features, codebase improvements, etc)
 

docs/documentation.rst

@@ -0,0 +1,76 @@
+example_brownian.py
+-------------------
+
+.. literalinclude:: ../examples/example_brownian.py
+   :language: python
+   :linenos:
+
+example_dask_chunk_OCMs.py
+--------------------------
+
+.. literalinclude:: ../examples/example_dask_chunk_OCMs.py
+   :language: python
+   :linenos:
+
+example_decaying_moving_eddy.py
+-------------------------------
+
+.. literalinclude:: ../examples/example_decaying_moving_eddy.py
+   :language: python
+   :linenos:
+
+example_globcurrent.py
+----------------------
+
+.. literalinclude:: ../examples/example_globcurrent.py
+   :language: python
+   :linenos:
+
+example_mitgcm.py
+-----------------
+
+.. literalinclude:: ../examples/example_mitgcm.py
+   :language: python
+   :linenos:
+
+example_moving_eddies.py
+------------------------
+
+.. literalinclude:: ../examples/example_moving_eddies.py
+   :language: python
+   :linenos:
+
+example_nemo_curvilinear.py
+---------------------------
+
+.. literalinclude:: ../examples/example_nemo_curvilinear.py
+   :language: python
+   :linenos:
+
+example_ofam.py
+---------------
+
+.. literalinclude:: ../examples/example_ofam.py
+   :language: python
+   :linenos:
+
+example_peninsula.py
+--------------------
+
+.. literalinclude:: ../examples/example_peninsula.py
+   :language: python
+   :linenos:
+
+example_radial_rotation.py
+--------------------------
+
+.. literalinclude:: ../examples/example_radial_rotation.py
+   :language: python
+   :linenos:
+
+example_stommel.py
+------------------
+
+.. literalinclude:: ../examples/example_stommel.py
+   :language: python
+   :linenos:

docs/documentation/additional_examples.rst

@@ -0,0 +1,76 @@
+Documentation and Tutorials
+===========================
+
+Parcels has several documentation and tutorial Jupyter notebooks and scripts which go through various aspects of Parcels. Static versions of the notebooks are available below via the gallery in the site, with the interactive notebooks being available either completely online at the following `Binder link <https://mybinder.org/v2/gh/OceanParcels/parcels/master?labpath=docs%2Fexamples%2Fparcels_tutorial.ipynb>`_. Following the gallery of notebooks is a list of scripts which provide additional examples to users. You can work with the example notebooks and scripts locally by downloading :download:`parcels_tutorials.zip </_downloads/parcels_tutorials.zip>` and running with your own Parcels installation.
+
+.. nbgallery::
+   :caption: Overview
+   :name: tutorial-overview
+
+   ../examples/tutorial_parcels_structure.ipynb
+   ../examples/parcels_tutorial.ipynb
+   ../examples/tutorial_output.ipynb
+
+
+.. nbgallery::
+   :caption: Setting up FieldSets
+   :name: tutorial-fieldsets
+
+   ../examples/documentation_indexing.ipynb
+   ../examples/tutorial_nemo_curvilinear.ipynb
+   ../examples/tutorial_nemo_3D.ipynb
+   ../examples/tutorial_NestedFields.ipynb
+   ../examples/tutorial_timevaryingdepthdimensions.ipynb
+   ../examples/tutorial_periodic_boundaries.ipynb
+   ../examples/tutorial_interpolation.ipynb
+   ../examples/tutorial_unitconverters.ipynb
+   ../examples/tutorial_timestamps.ipynb
+
+
+.. nbgallery::
+   :caption: Creating ParticleSets
+   :name: tutorial-particlesets
+
+   ../examples/tutorial_jit_vs_scipy.ipynb
+   ../examples/tutorial_delaystart.ipynb
+
+
+.. nbgallery::
+   :caption: Writing kernels to be executed on each particle
+   :name: tutorial-kernels
+
+   ../examples/tutorial_diffusion.ipynb
+   ../examples/tutorial_sampling.ipynb
+   ../examples/tutorial_particle_field_interaction.ipynb
+   ../examples/tutorial_interaction.ipynb
+   ../examples/tutorial_analyticaladvection.ipynb
+   ../examples/tutorial_kernelloop.ipynb
+
+
+.. nbgallery::
+   :caption: Other tutorials
+   :name: tutorial-other
+
+   ../examples/documentation_MPI.ipynb
+   ../examples/documentation_stuck_particles.ipynb
+   ../examples/documentation_unstuck_Agrid.ipynb
+   ../examples/documentation_LargeRunsOutput.ipynb
+   ../examples/documentation_geospatial.ipynb
+   ../examples/documentation_advanced_zarr.ipynb
+
+
+.. nbgallery::
+   :caption: Worked examples
+   :name: tutorial-examples
+
+   ../examples/tutorial_Argofloats.ipynb
+   ../examples/documentation_homepage_animation.ipynb
+
+
+Python Example Scripts
+----------------------
+
+
+.. toctree::
+
+   additional_examples

docs/documentation/index.rst

@@ -216,14 +216,14 @@
     "%pylab inline\n",
     "import os\n",
     "import time\n",
-    "from datetime import timedelta as delta\n",
+    "from datetime import timedelta\n",
     "from glob import glob\n",
     "\n",
     "import matplotlib.pyplot as plt\n",
     "import numpy as np\n",
     "import psutil\n",
     "\n",
-    "from parcels import AdvectionRK4, FieldSet, JITParticle, ParticleSet\n",
+    "import parcels\n",
     "\n",
     "\n",
     "def set_cms_fieldset(cs):\n",
@@ -235,20 +235,24 @@
     "\n",
     "    if cs not in [\"auto\", False]:\n",
     "        cs = {\"time\": (\"time\", 1), \"lat\": (\"latitude\", cs), \"lon\": (\"longitude\", cs)}\n",
-    "    return FieldSet.from_netcdf(files, variables, dimensions, chunksize=cs)\n",
+    "    return parcels.FieldSet.from_netcdf(files, variables, dimensions, chunksize=cs)\n",
     "\n",
     "\n",
     "func_time = []\n",
     "mem_used_GB = []\n",
     "chunksize = [128, 256, 512, 768, 1024, 1280, 1536, 1792, 2048, 2610, \"auto\", False]\n",
     "for cs in chunksize:\n",
     "    fieldset = set_cms_fieldset(cs)\n",
-    "    pset = ParticleSet(\n",
-    "        fieldset=fieldset, pclass=JITParticle, lon=[0], lat=[0], repeatdt=delta(hours=1)\n",
+    "    pset = parcels.ParticleSet(\n",
+    "        fieldset=fieldset,\n",
+    "        pclass=parcels.JITParticle,\n",
+    "        lon=[0],\n",
+    "        lat=[0],\n",
+    "        repeatdt=timedelta(hours=1),\n",
     "    )\n",
     "\n",
     "    tic = time.time()\n",
-    "    pset.execute(AdvectionRK4, dt=delta(hours=1))\n",
+    "    pset.execute(parcels.AdvectionRK4, dt=timedelta(hours=1))\n",
     "    func_time.append(time.time() - tic)\n",
     "    process = psutil.Process(os.getpid())\n",
     "    mem_B_used = process.memory_info().rss\n",
@@ -387,19 +391,23 @@
     "            \"lat\": (\"latitude\", cs),\n",
     "            \"lon\": (\"longitude\", cs),\n",
     "        }\n",
-    "    return FieldSet.from_netcdf(files, variables, dimensions, chunksize=cs)\n",
+    "    return parcels.FieldSet.from_netcdf(files, variables, dimensions, chunksize=cs)\n",
     "\n",
     "\n",
     "chunksize_3D = [128, 256, 512, 768, 1024, 1280, 1536, 1792, 2048, 2610, \"auto\", False]\n",
     "func_time3D = []\n",
     "for cs in chunksize_3D:\n",
     "    fieldset = set_cms_fieldset_3D(cs)\n",
-    "    pset = ParticleSet(\n",
-    "        fieldset=fieldset, pclass=JITParticle, lon=[0], lat=[0], repeatdt=delta(hours=1)\n",
+    "    pset = parcels.ParticleSet(\n",
+    "        fieldset=fieldset,\n",
+    "        pclass=parcels.JITParticle,\n",
+    "        lon=[0],\n",
+    "        lat=[0],\n",
+    "        repeatdt=timedelta(hours=1),\n",
     "    )\n",
     "\n",
     "    tic = time.time()\n",
-    "    pset.execute(AdvectionRK4_3D, dt=delta(hours=1))\n",
+    "    pset.execute(AdvectionRK4_3D, dt=timedelta(hours=1))\n",
     "    func_time3D.append(time.time() - tic)"
    ]
   },