[DOCS] Update documentation of tutorial_write_in_kernel (#2657)

* Update tutorial_write_in_kernel

* Add tutorial_write_in_kernel to user guide list

* Add write_in_kernel to migration guide

* Separate output cell

Author: erikvansebille

docs/user_guide/examples/tutorial_write_in_kernel.ipynb

@@ -111,7 +111,11 @@
    "cell_type": "code",
    "execution_count": null,
    "id": "9",
-   "metadata": {},
+   "metadata": {
+    "tags": [
+     "hide-output"
+    ]
+   },
    "outputs": [],
    "source": [
     "# Load the CopernicusMarine data in the Agulhas region from the example_datasets\n",
@@ -187,7 +191,11 @@
    "cell_type": "code",
    "execution_count": null,
    "id": "14",
-   "metadata": {},
+   "metadata": {
+    "tags": [
+     "hide-output"
+    ]
+   },
    "outputs": [],
    "source": [
     "output_file_both = parcels.ParticleFile(\n",
@@ -217,16 +225,24 @@
     "    runtime=np.timedelta64(4, \"h\"),\n",
     "    dt=np.timedelta64(15, \"m\"),\n",
     "    output_file=output_file_both,  # the file that writes at regular intervals\n",
-    ")\n",
-    "\n",
+    ")"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "15",
+   "metadata": {},
+   "outputs": [],
+   "source": [
     "df = parcels.read_particlefile(output_file_both.path)\n",
     "assert len(df) == 6  # 2 particles * 3 time steps (0h, 2h, 2h15m)\n",
     "df"
    ]
   },
   {
    "cell_type": "markdown",
-   "id": "15",
+   "id": "16",
    "metadata": {},
    "source": [
     "As you can see in the output above, each particle is now written three times, at 0h, at 2h, and at 2h15m when the particle is deleted.\n",

docs/user_guide/index.md

@@ -51,6 +51,7 @@ examples/tutorial_delaystart.ipynb
 examples/explanation_kernelloop.md
 examples/tutorial_sampling.ipynb
 examples/tutorial_statuscodes.ipynb
+examples/tutorial_write_in_kernel.ipynb
 ```
 
 ```{toctree}

docs/user_guide/v4-migration.md

@@ -44,6 +44,7 @@ Version 4 of Parcels is unreleased at the moment. The information in this migrat
 - The `name` argument in `ParticleFile` has been replaced by `path` and can now be a string or a Path.
 - The `chunks` argument in `ParticleFile` has been removed.
 - The `to_write="once"`option has been removed. A variable can now only be either written at every output time step, or not written at all.
+- Particles are not written when they are deleted. You can use the functionality to call `ParticleFile.write()` inside a kernel to write out deleted particles if you want to keep track of them.
 
 ## Field