Rename RST files to Markdown extension

Author: VeckoTheGecko

docs/community/contributing.rst docs/community/contributing.mddocs/community/contributing.rst renamed to docs/community/contributing.md

@@ -1,65 +1,61 @@
-Contributing to Parcels
-=======================
+# Contributing to Parcels
 
-Why contribute?
----------------
+## Why contribute?
 
 `Lagrangian Ocean Analysis <https://doi.org/10.1016/j.ocemod.2017.11.008>`_ is one of the primary modelling tools available to oceanographers to understand how ocean currents transport material. This modelling approach allows researchers to model the ocean and understand the `movement of water <https://doi.org/10.1029/2023GL105662>`_ in the ocean itself (or even `on other planets <https://doi.org/10.3847/1538-4357/ac9d94>`_), as well as the transport of `nutrients <https://doi.org/10.1029/2023GL108001>`_, `marine organisms <https://doi.org/10.3354/meps14526>`_, `oil <https://doi.org/10.1590/0001-3765202220210391>`_, `plastic <https://doi.org/10.1038/s41561-023-01216-0>`_, as well as `almost <https://doi.org/10.1016/j.robot.2024.104730>`_ `anything <https://doi.org/10.1111/cobi.14295>`_ `else <https://doi.org/10.1016/j.marpolbul.2023.115254>`_ that would be adrift at sea. Since ocean currents play a key role in climate by storing heat and carbon, and also in the formation of the 'plastic soup', understanding transport phenomena in the ocean is crucial to support a more sustainable future.
 
-The Parcels code, for which development started in 2015, is now one of the most widely used tools for Lagrangian Ocean Analysis. It's used by dozens of groups around the world - see `this list <https://oceanparcels.org/papers-citing-parcels#papers-citing-parcels>`_ for a full list of the peer-reviewed articles using Parcels. Its flexibility for users to create new, custom 'behaviours' (i.e. let virtual particles be controlled by other mechanics than only the ocean flow) and its compatibility with many different types of hydrodynamic input data are the two key features.
+The Parcels code, for which development started in 2015, is now one of the most widely used tools for Lagrangian Ocean Analysis. It's used by dozens of groups around the world - see `this list <https://oceanparcels.org/papers-citing-parcels#papers-citing-parcels>`\_ for a full list of the peer-reviewed articles using Parcels. Its flexibility for users to create new, custom 'behaviours' (i.e. let virtual particles be controlled by other mechanics than only the ocean flow) and its compatibility with many different types of hydrodynamic input data are the two key features.
 
 .. note::
 
     Want to learn more about Lagrangian ocean analysis? Then look at `Lagrangian ocean analysis: Fundamentals and practices <https://www.sciencedirect.com/science/article/pii/S1463500317301853>`_ for a review of the literature.
 
-----
+---
 
 There are two primary groups that contribute to Parcels; oceanographers who bring domain specific understanding about the physical processes and modelling approaches, as well as software developers who bring their experience working with code. **All contributions are welcome no matter your background or level of experience**.
 
 .. note::
 
     The first component of this documentation is geared to those new to open source. Already familiar with GitHub and open source? Skip ahead to the `Development`_ section.
 
-What is open source?
---------------------
+## What is open source?
 
 Open source is a category of software that is open to the public, meaning that anyone is able to look at, modify, and improve the software. Compare this to closed source software (e.g., Microsoft Word, or Gmail) where only those working for the company on the product are able to look at the source code, or make improvements.
 
-Software being open source allows bugs in the code to be quickly identified and fixed, as well as fosters communities of people involved on projects. Most open source software have permissible licenses making them free to modify, and use even in commercial settings. Parcels, for example, is open source and `licensed under the MIT License <https://github.com/OceanParcels/parcels/blob/main/LICENSE.md>`_.
+Software being open source allows bugs in the code to be quickly identified and fixed, as well as fosters communities of people involved on projects. Most open source software have permissible licenses making them free to modify, and use even in commercial settings. Parcels, for example, is open source and `licensed under the MIT License <https://github.com/OceanParcels/parcels/blob/main/LICENSE.md>`\_.
 
-This visibility of the codebase results in a higher quality, as well as a more transparent and stable product. This is important in research for reproducibility, as well as in industry where stability is crucial. Open source is not some niche category of software, but in fact `forms the backbone of modern computing and computing infrastructure <https://www.newstatesman.com/science-tech/2016/08/how-linux-conquered-world-without-anyone-noticing>`_ and is used widely in industry. A lot of the digital services that you use (paid, or free) depend on open source code in one way or another.
+This visibility of the codebase results in a higher quality, as well as a more transparent and stable product. This is important in research for reproducibility, as well as in industry where stability is crucial. Open source is not some niche category of software, but in fact `forms the backbone of modern computing and computing infrastructure <https://www.newstatesman.com/science-tech/2016/08/how-linux-conquered-world-without-anyone-noticing>`\_ and is used widely in industry. A lot of the digital services that you use (paid, or free) depend on open source code in one way or another.
 
 Most open source code is managed through a version control system called Git. Once you get past the Git specific terminology, the fundamental nature of it is quite understandable. To give an overview: Git, which you can install on your local machine, is a tool which allows you to create snapshots (aka., ”commits”) of a codebase. These snapshots each have a custom message attached to it, forming a time-line for the life of the project. This allows you to incrementally make updates to a codebase, while also having full control to undo any changes (you can even use Git to see which line of code was written by who).
 
 A codebase (in Git terms, this is called a “repository” or “repo” for short) can be uploaded to a platform such as GitHub for hosting purposes, allowing for multiple people to be involved in a project. These platforms add a social media and project management aspect, where tasks can be created (these tasks are called “issues”, and can represent bugs, suggested features, or documentation improvements), assigned to people, and be addressed in changes to the codebase (i.e., addressed in a “pull request”, which details exactly which parts of the codebase need to change to fix a particular issue). A common workflow is for an issue to be created, discussed, and then addressed by one or more pull requests.
 
-Exactly how to use Git and GitHub is beyond the scope of this documentation, and there are many tutorials online on how to do that (here are some good ones: `Version Control with Git by Software carpentry <https://swcarpentry.github.io/git-novice/>`_,  `Learn Git by freeCodeCamp.org <https://www.youtube.com/watch?v=zTjRZNkhiEU>`_).
+Exactly how to use Git and GitHub is beyond the scope of this documentation, and there are many tutorials online on how to do that (here are some good ones: `Version Control with Git by Software carpentry <https://swcarpentry.github.io/git-novice/>`_, `Learn Git by freeCodeCamp.org <https://www.youtube.com/watch?v=zTjRZNkhiEU>`_).
 
-Your first contribution
------------------------
+## 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/index.rst>`_
-- Suggest improvements to `documentation <../index.rst>`_
+- Suggest improvements to `tutorials <../documentation/index.rst>`\_
+- Suggest improvements to `documentation <../index.rst>`\_
 - Write code (fix bugs, implement features, codebase improvements, etc)
 
 All of these require you to [make an account on GitHub](https://github.com/signup), so that should be your first step.
 
 If you want to suggest quick edits to the documentation, it's as easy as going to the page and clicking "Edit on GitHub" in the righthand panel. For other changes, it's a matter of looking through the `issue tracker <https://github.com/OceanParcels/parcels/issues>`_ which documents tasks that are being considered. Pay particular attention to `issues tagged with "good first issue" <https://github.com/OceanParcels/parcels/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22>`_, as these are tasks that don't require deep familiarity with the codebase. Once you've chosen an issue you would like to contribute towards, comment on it to flag your interest in working on it. This allows the community to know who's interested, and provide any guidance in its implementation (maybe the scope has changed since the issue was last updated).
 
-If you're having trouble using Parcels, feel free to create a discussion in our Discussions tab and we'll be happy to support. Want to suggest a feature, or have encountered a problem that is a result of a bug in Parcels, then search for an issue in the tracker or `create a new one <https://github.com/OceanParcels/parcels/issues/new/choose>`_ with the relevant details.
+If you're having trouble using Parcels, feel free to create a discussion in our Discussions tab and we'll be happy to support. Want to suggest a feature, or have encountered a problem that is a result of a bug in Parcels, then search for an issue in the tracker or `create a new one <https://github.com/OceanParcels/parcels/issues/new/choose>`\_ with the relevant details.
 
-In the `Projects panel <https://github.com/OceanParcels/parcels/projects?query=is%3Aopen>`_, you'll see the "Parcels development" project. This is used by the core development team for project management, as well as drafting up new ideas for the codebase that aren't mature enough to be issues themselves. Everything in "backlog" is not being actively worked on and is fair game for open source contributions.
+In the `Projects panel <https://github.com/OceanParcels/parcels/projects?query=is%3Aopen>`\_, you'll see the "Parcels development" project. This is used by the core development team for project management, as well as drafting up new ideas for the codebase that aren't mature enough to be issues themselves. Everything in "backlog" is not being actively worked on and is fair game for open source contributions.
 
-.. _editing-parcels-code:
+.. \_editing-parcels-code:
 
-Development
------------
+## Development
 
 Environment setup
-~~~~~~~~~~~~~~~~~
+
+```
 
 .. note::
 
@@ -150,3 +146,4 @@ Code guidelines
 ----
 
 That's it! Thank you for reading and we'll see you on GitHub 😁.
+```

docs/community/index.rst docs/community/index.mddocs/community/index.rst renamed to docs/community/index.md

@@ -1,22 +1,19 @@
-Community
-=========
+# Community
 
 These sections contain documentation relevant to the Parcels community.
 See the sections in the primary sidebar and below to explore.
 
 .. toctree::
-    :caption: User documentation
-    :maxdepth: 1
+:caption: User documentation
+:maxdepth: 1
 
     contributing
     Versioning Policy <policies>
     Release Notes <https://github.com/OceanParcels/Parcels/releases>
     Parcels v4.0 Migration Guide <v4-migration>
 
-
-
 .. toctree::
-    :caption: Maintainer documentation
-    :maxdepth: 1
+:caption: Maintainer documentation
+:maxdepth: 1
 
     maintainer

docs/documentation/additional_examples.md

@@ -0,0 +1,61 @@
+# Python Example Scripts
+
+## example_brownian.py
+
+.. literalinclude:: ../examples/example_brownian.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,66 @@
+# 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/main?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_croco_3D.ipynb
+../examples/tutorial_timevaryingdepthdimensions.ipynb
+../examples/tutorial_periodic_boundaries.ipynb
+../examples/tutorial_interpolation.ipynb
+../examples/tutorial_unitconverters.ipynb
+
+.. nbgallery::
+:caption: Creating ParticleSets
+:name: tutorial-particlesets
+
+../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/tutorial_peninsula_AvsCgrid.ipynb
+../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