Convert documentation from ReStructured Text to Markdown

docs/.gitlab-ci.yml

@@ -13,7 +13,7 @@ build-documentation:
 
   before_script:
     - cd $CI_PROJECT_DIR/docs
-    - pip install sphinx_rtd_theme
+    - pip install sphinx_rtd_theme myst-parser
   script:
     - make html
 

docs/architecture/index.md

+# Architecture
+
+We follow the principles of infrastructure as code and we decompose configuration in data and templates.
\ No newline at end of file

docs/conf.py

@@ -4,10 +4,17 @@ copyright = '2023, GÉANT Vereniging'
 author = 'GÉANT Orchestration and Automation Team'
 
 # -- General configuration ---------------------------------------------------
-extensions = ['sphinx_rtd_theme']
+extensions = ['sphinx_rtd_theme', 'myst_parser']
 
 templates_path = ['templates']
 exclude_patterns = ['build', 'Thumbs.db', '.DS_Store', 'venv']
+source_suffix = {
+    '.md': 'markdown'
+}
+
+# -- Options for Markdown support --------------------------------------------
+myst_enable_extensions = ['replacements', 'strikethrough']
+suppress_warnings = ['myst.strikethrough']
 
 # -- Options for HTML output -------------------------------------------------
 html_theme = 'sphinx_rtd_theme'

docs/index.md

+# GÉANT Automation Platform (GAP)
+
+Welcome to the documentation of the GÉANT Automation Platform, also known simply as GAP. \
+The focus of this platform is configuration management and service orchestration for the GÉANT IP/MPLS network.
+
+## Table of Contents
+```{toctree}
+overview/index.md
+architecture/index.md
+```

docs/index.rst

-GÉANT Automation Platform (GAP)
-===============================
-
-.. toctree::
-   :maxdepth: 2
-   :glob:
-   :Caption: Contents
-
-   overview/*
-
-Indices and tables
-==================
-
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`

docs/make.bat

-@ECHO OFF
-
-pushd %~dp0
-
-REM Command file for Sphinx documentation
-
-if "%SPHINXBUILD%" == "" (
-	set SPHINXBUILD=sphinx-build
-)
-set SOURCEDIR=.
-set BUILDDIR=_build
-
-%SPHINXBUILD% >NUL 2>NUL
-if errorlevel 9009 (
-	echo.
-	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
-	echo.installed, then set the SPHINXBUILD environment variable to point
-	echo.to the full path of the 'sphinx-build' executable. Alternatively you
-	echo.may add the Sphinx directory to PATH.
-	echo.
-	echo.If you don't have Sphinx installed, grab it from
-	echo.https://www.sphinx-doc.org/
-	exit /b 1
-)
-
-if "%1" == "" goto help
-
-%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
-goto end
-
-:help
-%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
-
-:end
-popd

docs/overview/index.rst → docs/overview/index.md

-Overview
-==============
+# Overview
 
 Configuration management is the process that maintains consistency and integrity of the network and of the services
 built on top of it ensuring that it meets requirements in terms of functionalities, performances, and security.