Avoid duplicated documentation in README.md and .rst

[hiker]

An example is the file examples/nemo/README.md, which could mostly be copied into user_guide/tutorials_and_examples.rst.

The following patch does most of the work, but I ran out of time trying to figure out dealing with links to tutorials_and_examples.rst, as e.g. used in the developer's guide:

psyir_backends.rst:run Dawn, see :ref:`user_guide:nemo-eg4-sir` the NEMO API example 4.

You need to do pip install myst-parser (and we need to add this to the PSyclone dependencies), then the following patch will already copy the selected part from README.me into the .rst. It converts the first 4 examples (as in: I have combined the two descriptions for the first 4 examples to contain all the information we had before), so example 5, ... will be duplicated for now. But example 4 has an external link

diff --git a/doc/user_guide/conf.py b/doc/user_guide/conf.py
index 6a055272a..237c9dc98 100644
--- a/doc/user_guide/conf.py
+++ b/doc/user_guide/conf.py
@@ -42,6 +42,7 @@ extensions = ['sphinx.ext.autodoc', 'sphinx.ext.doctest',
               'sphinxcontrib.bibtex', 'sphinx_tabs.tabs',
               'sphinx_autodoc_typehints',
               'apilinks',
+              'myst_parser'
               ]
 bibtex_bibfiles = ['../bibliography/references.bib']
 
diff --git a/doc/user_guide/tutorials_and_examples.rst b/doc/user_guide/tutorials_and_examples.rst
index 6b6ff19b4..090d14c01 100644
--- a/doc/user_guide/tutorials_and_examples.rst
+++ b/doc/user_guide/tutorials_and_examples.rst
@@ -737,41 +737,16 @@ algorithm layer run:
     cd eg20/
     psyclone-kern -gen alg ../code/testkern_mod.F90
 
-NEMO Examples
--------------
+.. Include the example description from the README:
 
-These examples may all be found in the ``examples/nemo`` directory.
+.. include:: ../../examples/nemo/README.md
+  :parser: myst
+  :start-after: <!-- THIS IS INCLUDED IN THE USER GUIDE -->
+  :end-before: <!-- END THIS IS INCLUDED IN THE USER GUIDE -->
 
-Example 1: OpenMP parallelisation of tra_adv
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-Demonstrates the use of PSyclone to parallelise loops in a NEMO
-tracer-advection benchmark using OpenMP for CPUs and for GPUs.
-
-Example 2: OpenMP parallelisation of traldf_iso
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-Demonstrates the use of PSyclone to parallelise in some NEMO
-tracer-diffusion code using OpenMP for CPUs and for GPUs.
-
-Example 3: OpenACC parallelisation of tra_adv
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-Demonstrates the introduction of simple OpenACC parallelisation (using the
-``data`` and ``kernels`` directives) for a NEMO tracer-advection benchmark.
 
 .. _nemo-eg4-sir:
 
-Example 4: Transforming Fortran code to the SIR
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-Demonstrates that simple Fortran code can be transformed to the Stencil
-Intermediate Representation (SIR). The SIR is the front-end language to DAWN
-(https://github.com/MeteoSwiss-APN/dawn), a tool which generates
-optimised cuda, or gridtools code. Thus various simple Fortran
-examples and the computational part of the tracer-advection benchmark
-can be transformed to optimised cuda and/or gridtools code by using
-PSyclone and then DAWN.
 
 Example 5: Kernel Data Extraction
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

[hiker]

Similarly, example 5 in the rst contains:

one (see :ref:`extraction_libraries` for details).

which then must be moved into the README.md