Repository: kedro-org/kedro

Issue:
Migrate from recommonmark to MyST
## Description
We use recommonmark plugin to write docs in markdown format, but this package has been deprecated and archived. The recommendation is to use [MyST](https://github.com/executablebooks/MyST-Parser) instead.

See https://github.com/readthedocs/recommonmark/issues/221 for more info.

## Context
Using mermaid in our docs as proposed by #1392 and any other future changes might require a switch to `MyST` as recommended by [sphinxcontrib-mermaid](https://github.com/mgaitan/sphinxcontrib-mermaid#markdown-support). 

Trying an older suggestion `sphinxcontrib-mermaid` (version 0.7) doesn't work, so it might still require the migration to MyST.




Discussion:
Love this 
@avan-sh I accidentally got here while trying to update #1392! ~I will try and close this out in the same issue, then (or I can separate it out, never say no to a commit).~

edit: Definitely making a separate PR; turns out so many anchor links are broken, since they're not currently getting checked?

Resolving patch:
diff --git a/kedro/templates/project/{{ cookiecutter.repo_name }}/docs/source/conf.py b/kedro/templates/project/{{ cookiecutter.repo_name }}/docs/source/conf.py
--- a/kedro/templates/project/{{ cookiecutter.repo_name }}/docs/source/conf.py	
+++ b/kedro/templates/project/{{ cookiecutter.repo_name }}/docs/source/conf.py	
@@ -20,7 +20,6 @@
 import re
 
 from kedro.framework.cli.utils import find_stylesheets
-from recommonmark.transform import AutoStructify
 
 from {{ cookiecutter.python_package }} import __version__ as release
 
@@ -53,7 +52,7 @@
     "sphinx.ext.viewcode",
     "sphinx.ext.mathjax",
     "nbsphinx",
-    "recommonmark",
+    "myst_parser",
     "sphinx_copybutton",
 ]
 
@@ -223,6 +222,3 @@ def setup(app):
     # add Kedro stylesheets
     for stylesheet in find_stylesheets():
         app.add_css_file(stylesheet)
-    # enable rendering RST tables in Markdown
-    app.add_config_value("recommonmark_config", {"enable_eval_rst": True}, True)
-    app.add_transform(AutoStructify)
diff --git a/kedro/templates/project/{{ cookiecutter.repo_name }}/src/setup.py b/kedro/templates/project/{{ cookiecutter.repo_name }}/src/setup.py
--- a/kedro/templates/project/{{ cookiecutter.repo_name }}/src/setup.py	
+++ b/kedro/templates/project/{{ cookiecutter.repo_name }}/src/setup.py	
@@ -29,11 +29,11 @@
             "sphinx_rtd_theme==0.5.1",
             "nbsphinx==0.8.1",
             "nbstripout~=0.4",
-            "recommonmark==0.7.1",
             "sphinx-autodoc-typehints==1.11.1",
             "sphinx_copybutton==0.3.1",
             "ipykernel>=5.3, <7.0",
             "Jinja2<3.1.0",
+            "myst-parser~=0.17.2",
         ]
     },
 )


Test patch:
diff --git a/features/steps/test_starter/{{ cookiecutter.repo_name }}/docs/source/conf.py b/features/steps/test_starter/{{ cookiecutter.repo_name }}/docs/source/conf.py
--- a/features/steps/test_starter/{{ cookiecutter.repo_name }}/docs/source/conf.py	
+++ b/features/steps/test_starter/{{ cookiecutter.repo_name }}/docs/source/conf.py	
@@ -17,8 +17,6 @@
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 #
 import re
-
-from recommonmark.transform import AutoStructify
 from {{cookiecutter.python_package}} import __version__ as release
 
 from kedro.framework.cli.utils import find_stylesheets
@@ -52,8 +50,8 @@
     "sphinx.ext.viewcode",
     "sphinx.ext.mathjax",
     "nbsphinx",
-    "recommonmark",
     "sphinx_copybutton",
+    "myst_parser",
 ]
 
 # enable autosummary plugin (table of contents for modules/classes/class
@@ -222,6 +220,3 @@ def setup(app):
     # add Kedro stylesheets
     for stylesheet in find_stylesheets():
         app.add_css_file(stylesheet)
-    # enable rendering RST tables in Markdown
-    app.add_config_value("recommonmark_config", {"enable_eval_rst": True}, True)
-    app.add_transform(AutoStructify)
diff --git a/features/steps/test_starter/{{ cookiecutter.repo_name }}/src/setup.py b/features/steps/test_starter/{{ cookiecutter.repo_name }}/src/setup.py
--- a/features/steps/test_starter/{{ cookiecutter.repo_name }}/src/setup.py	
+++ b/features/steps/test_starter/{{ cookiecutter.repo_name }}/src/setup.py	
@@ -29,11 +29,11 @@
             "sphinx_rtd_theme==0.5.1",
             "nbsphinx==0.8.1",
             "nbstripout~=0.4",
-            "recommonmark==0.7.1",
             "sphinx-autodoc-typehints==1.11.1",
             "sphinx_copybutton==0.3.1",
             "ipykernel>=5.3, <7.0",
             "Jinja2<3.1.0",
+            "myst-parser~=0.17.2",
         ]
     },
 )