Convert RST syntax to Markdown syntax

Author: VeckoTheGecko

docs/community/contributing.md

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

docs/community/index.md

@@ -2,60 +2,70 @@
 
 ## example_brownian.py
 
-.. literalinclude:: ../examples/example_brownian.py
+```{literalinclude} ../examples/example_brownian.py
 :language: python
 :linenos:
+```
 
 ## example_decaying_moving_eddy.py
 
-.. literalinclude:: ../examples/example_decaying_moving_eddy.py
+```{literalinclude} ../examples/example_decaying_moving_eddy.py
 :language: python
 :linenos:
+```
 
 ## example_globcurrent.py
 
-.. literalinclude:: ../examples/example_globcurrent.py
+```{literalinclude} ../examples/example_globcurrent.py
 :language: python
 :linenos:
+```
 
 ## example_mitgcm.py
 
-.. literalinclude:: ../examples/example_mitgcm.py
+```{literalinclude} ../examples/example_mitgcm.py
 :language: python
 :linenos:
+```
 
 ## example_moving_eddies.py
 
-.. literalinclude:: ../examples/example_moving_eddies.py
+```{literalinclude} ../examples/example_moving_eddies.py
 :language: python
 :linenos:
+```
 
 ## example_nemo_curvilinear.py
 
-.. literalinclude:: ../examples/example_nemo_curvilinear.py
+```{literalinclude} ../examples/example_nemo_curvilinear.py
 :language: python
 :linenos:
+```
 
 ## example_ofam.py
 
-.. literalinclude:: ../examples/example_ofam.py
+```{literalinclude} ../examples/example_ofam.py
 :language: python
 :linenos:
+```
 
 ## example_peninsula.py
 
-.. literalinclude:: ../examples/example_peninsula.py
+```{literalinclude} ../examples/example_peninsula.py
 :language: python
 :linenos:
+```
 
 ## example_radial_rotation.py
 
-.. literalinclude:: ../examples/example_radial_rotation.py
+```{literalinclude} ../examples/example_radial_rotation.py
 :language: python
 :linenos:
+```
 
 ## example_stommel.py
 
-.. literalinclude:: ../examples/example_stommel.py
+```{literalinclude} ../examples/example_stommel.py
 :language: python
 :linenos:
+```

docs/documentation/additional_examples.md

@@ -1,16 +1,17 @@
 # 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.
+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::
+```{nbgallery}
 :caption: Overview
 :name: tutorial-overview
 
 ../examples/tutorial_parcels_structure.ipynb
 ../examples/parcels_tutorial.ipynb
 ../examples/tutorial_output.ipynb
+```
 
-.. nbgallery::
+```{nbgallery}
 :caption: Setting up FieldSets
 :name: tutorial-fieldsets
 
@@ -22,14 +23,16 @@ Parcels has several documentation and tutorial Jupyter notebooks and scripts whi
 ../examples/tutorial_periodic_boundaries.ipynb
 ../examples/tutorial_interpolation.ipynb
 ../examples/tutorial_unitconverters.ipynb
+```
 
-.. nbgallery::
+```{nbgallery}
 :caption: Creating ParticleSets
 :name: tutorial-particlesets
 
 ../examples/tutorial_delaystart.ipynb
+```
 
-.. nbgallery::
+```{nbgallery}
 :caption: Writing kernels to be executed on each particle
 :name: tutorial-kernels
 
@@ -39,8 +42,9 @@ Parcels has several documentation and tutorial Jupyter notebooks and scripts whi
 ../examples/tutorial_interaction.ipynb
 ../examples/tutorial_analyticaladvection.ipynb
 ../examples/tutorial_kernelloop.ipynb
+```
 
-.. nbgallery::
+```{nbgallery}
 :caption: Other tutorials
 :name: tutorial-other
 
@@ -51,16 +55,18 @@ Parcels has several documentation and tutorial Jupyter notebooks and scripts whi
 ../examples/documentation_LargeRunsOutput.ipynb
 ../examples/documentation_geospatial.ipynb
 ../examples/documentation_advanced_zarr.ipynb
+```
 
-.. nbgallery::
+```{nbgallery}
 :caption: Worked examples
 :name: tutorial-examples
 
 ../examples/tutorial_Argofloats.ipynb
 ../examples/documentation_homepage_animation.ipynb
+```
 
 ## Python Example Scripts
 
-.. toctree::
-
+```{toctree}
 additional_examples
+```

docs/documentation/index.md

@@ -1,17 +1,18 @@
 # Parcels documentation
 
-Welcome to the documentation of Parcels. **Parcels** provides a set of Python classes and methods to create customisable particle tracking simulations using gridded output from (ocean) circulation models. Parcels can be used to track passive and active particulates such as water, plankton, `plastic <http://www.topios.org/>`_ and `fish <https://github.com/Jacketless/IKAMOANA>`_.
+Welcome to the documentation of Parcels. **Parcels** provides a set of Python classes and methods to create customisable particle tracking simulations using gridded output from (ocean) circulation models. Parcels can be used to track passive and active particulates such as water, plankton, [plastic](http://www.topios.org/) and [fish](https://github.com/Jacketless/IKAMOANA).
 
-.. figure:: \_static/homepage.gif
+```{figure} _static/homepage.gif
 :class: dark-light
+```
 
-_Animation of virtual particles carried by ocean surface flow in the global oceans. The particles are advected with Parcels in data from the_ `NEMO Ocean Model <https://www.nemo-ocean.eu/>`\_.
+_Animation of virtual particles carried by ocean surface flow in the global oceans. The particles are advected with Parcels in data from the_ [NEMO Ocean Model](https://www.nemo-ocean.eu/).
 
-Here you'll find `installation instructions <installation.rst>`_, `tutorials and documentation <documentation/index.rst>`_, and the `API reference <reference.rst>`\_ for Parcels. You can browse the documentation for older versions by using the version switcher in the left sidebar.
+Here you'll find [installation instructions](installation.md), [tutorials and documentation](documentation/index.md), and the [API reference](reference.md) for Parcels. You can browse the documentation for older versions by using the version switcher in the left sidebar.
 
-If you need more help with Parcels, try the `Discussions page on GitHub <https://github.com/OceanParcels/parcels/discussions>`_. If you think you found a bug, file an `Issue on GitHub <https://github.com/OceanParcels/parcels/issues>`_. If you want to help improve Parcels, see the `Contributing <community/contributing.rst>`\_ page.
+If you need more help with Parcels, try the [Discussions page on GitHub](https://github.com/OceanParcels/parcels/discussions). If you think you found a bug, file an [Issue on GitHub](https://github.com/OceanParcels/parcels/issues). If you want to help improve Parcels, see the [Contributing](community/contributing.md) page.
 
-.. toctree::
+```{toctree}
 :maxdepth: 2
 :hidden:
 
@@ -22,3 +23,4 @@ Tutorials & Documentation <documentation/index>
 API reference <reference>
 Contributing, Release Notes and more <community/index>
 OceanParcels website <https://oceanparcels.org/>
+```

docs/index.md

@@ -1,54 +1,50 @@
 # Basic installation
 
-The simplest way to install the Parcels code is to use Anaconda and the `Parcels conda-forge package <https://anaconda.org/conda-forge/parcels>`\_ with the latest release of Parcels. This package will automatically install all the requirements for a fully functional installation of Parcels. This is the “batteries-included” solution probably suitable for most users. Note that we support Python 3.10 and higher.
+The simplest way to install the Parcels code is to use Anaconda and the [Parcels conda-forge package](https://anaconda.org/conda-forge/parcels) with the latest release of Parcels. This package will automatically install all the requirements for a fully functional installation of Parcels. This is the "batteries-included" solution probably suitable for most users. Note that we support Python 3.10 and higher.
 
-If you want to install the latest development version of Parcels and work with features that have not yet been officially released, you can follow the instructions for a `developer installation <#installation-for-developers>`\_.
+If you want to install the latest development version of Parcels and work with features that have not yet been officially released, you can follow the instructions for a [developer installation](#installation-for-developers).
 
 The steps below are the installation instructions for Linux, macOS and Windows.
 
-.. \_step 1 above:
+(step-1-above)=
 
 **Step 1:** Install Anaconda's Miniconda following the steps at https://docs.anaconda.com/miniconda/. If you're on Linux /macOS, the following assumes that you installed Miniconda to your home directory.
 
 **Step 2:** Start a terminal (Linux / macOS) or the Anaconda prompt (Windows). Activate the `base` environment of your Miniconda and create an environment containing Parcels, all its essential dependencies, `trajan` (a trajectory plotting dependency used in the notebooks) and the nice-to-have cartopy and jupyter packages:
 
-.. code-block:: bash
+```bash
+conda activate base
+conda create -n parcels -c conda-forge parcels trajan cartopy jupyter
+```
 
-    conda activate base
-    conda create -n parcels -c conda-forge parcels trajan cartopy jupyter
-
-.. note::
-
-    For some of the examples, ``pytest`` also needs to be installed. This can be quickly done with ``conda install -n parcels pytest`` which installs ``pytest`` directly into the newly created ``parcels`` environment.
+```{note}
+For some of the examples, `pytest` also needs to be installed. This can be quickly done with `conda install -n parcels pytest` which installs `pytest` directly into the newly created `parcels` environment.
+```
 
 **Step 3:** Activate the newly created Parcels environment:
 
-.. code-block:: bash
+```bash
+conda activate parcels
+```
 
-    conda activate parcels
-
-**Step 4:** Download `a zipped copy <https://docs.oceanparcels.org/en/latest/_downloads/307c382eb1813dc691e8a80d6c0098f7/parcels_tutorials.zip>`\_ of the Parcels tutorials and examples and unzip it.
+**Step 4:** Download [a zipped copy](https://docs.oceanparcels.org/en/latest/_downloads/307c382eb1813dc691e8a80d6c0098f7/parcels_tutorials.zip) of the Parcels tutorials and examples and unzip it.
 
 **Step 5:** Go to the unzipped folder and run one of the examples to validate that you have a working Parcels setup:
 
-.. code-block:: bash
-
+```bash
 python example_peninsula.py --fieldset 100 100
+```
 
 _Optionally:_ if you want to run all the examples and tutorials, start Jupyter and open the tutorial notebooks:
 
-.. code-block:: bash
-
+```bash
 jupyter notebook
+```
 
-.. note::
-
-The next time you start a terminal and want to work with Parcels, activate the environment with:
-
-.. code-block:: bash
-
-    conda activate parcels
+```{note}
+The next time you start a terminal and want to work with Parcels, activate the environment with `conda activate parcels`.
+```
 
 # Installation for developers
 
-See the `development section in our contributing guide <./community/contributing.rst#development>`\_ for development instructions.
+See the [development section in our contributing guide](./community/contributing.md#development) for development instructions.

docs/installation.md

@@ -1,5 +1,5 @@
 # Parcels API
 
-.. note::
-
+```{note}
 This section is a work in progress.
+```