Merge branch 'convert-to-md' into 'development'

Convert docs from rsx to markdown

See merge request !1

.gitlab-ci.yml

 stages:
-  - build-documentation
-  - lint-documentation
+  - documentation
 
 include:
   # Documentation pipelines, both building and linting

docs/.gitlab-ci.yml

 ---
 ##### Sphinx  - Generate documentation
 build-documentation:
-  stage: build-documentation
+  stage: documentation
   tags:
     - docker-executor
   image: sphinxdoc/sphinx:latest
@@ -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
 
@@ -23,19 +23,22 @@ build-documentation:
 
 ##### Vale    - Documentation linter
 lint-documentation:
-  stage: lint-documentation
+  stage: documentation
   image:
     name: jdkato/vale:latest
     entrypoint: [""]
 
   tags:
     - docker-executor
-  dependencies:
-    - build-documentation # Only run if documentation has been updated
+  needs:
+    - job: build-documentation # Only run when documentation has been built
+      artifacts: true
 
   before_script:
     - cd $CI_PROJECT_DIR/docs/vale
     - vale sync
 
   script:
-    - vale $CI_PROJECT_DIR/docs/build/html/_sources
+    - RESULT=$(vale $CI_PROJECT_DIR/docs/build/html/_sources)
+    - echo "$RESULT"
+    - if echo "$RESULT" | tail -n 1 | grep -q "✖" ; then echo -e "\n\n\n\033[0;31mPlease fix all Vale errors and warnings!\033[0m\n\n\n" && exit 1 ; else exit 0 ; fi

docs/architecture/index.md

+# Architecture
+
+We follow the principles of infrastructure as code, and we decompose configuration in data and templates.

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']
+exclude_patterns = ['build', 'Thumbs.db', '.DS_Store', 'venv', 'vale']
+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 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.
 
 In the context of the IP/MPLS layer and particularly the backbone routers, different teams manage configuration in
 different ways: to deploy new nodes and to operate the network, they use various tools en methods. Compliance and
-quality are checked afterwards: this approach requires much manual work and it is inherently error prone.
+quality are checked afterwards: this approach requires much manual work, and it is inherently error-prone.
 
 This project aims to standardize the configuration and the configuration deployment process by using Open Source tools
 and DevOps strategies: one single framework to deploy and to operate. Considering the network configuration as code and
@@ -14,8 +13,8 @@ managing it under a version control system (GitLab) will enable better visibilit
 standardize the way of working.
 
 The goal is to reduce configuration drifts and exceptions, Mean Time To Repair (MTTR) in case of fault, and possibly the
-number and the severity of incidents. To check configuration compliance before it gets deployed, several policies are in
-place: multiple non-production environments are used to automatically execute regression and acceptance tests, in order
+number and the severity of incidents. To verify configuration compliance before it gets deployed, several policies are in
+place. Multiple non-production environments are used to automatically run regression and acceptance tests, in order
 to ensure the highest quality and to detect problems early.
 
 Automated configuration management must be considered as the foundation of further work in network automation, towards

docs/vale/.vale.ini

@@ -4,7 +4,13 @@ MinAlertLevel = suggestion
 
 Vocab = geant-jargon, Sphinx
 
-Packages = RedHat, proselint, Readability
+Packages = RedHat, proselint
+
+[formats]
+txt = md
 
 [*]
-BasedOnStyles = Vale, RedHat, proselint, Readability
+BasedOnStyles = Vale, RedHat, proselint
+
+; Ignore the table of contents directive
+BlockIgnores = (?s) *(\x60\x60\x60{toctree}.*?\x60\x60\x60)