add README, update vale config

Signed-off-by: Karel van Klink <karel.vanklink@geant.org>

README.md

+# GÉANT Automation Platform
+
+Documentation for the GÉANT Automation Platform (GAP)
+
+## Writing documentation
+
+First, create a venv to work in: `python3 -m venv venv`
+
+Then, install `mkdocs-material`: `pip install mkdocs-material`
+
+To run the live preview server of MkDocs - which includes hot reloading - run `mkdocs serve`.
+
+## Testing documentation
+To verify that documentation passes the linting pipeline, install `vale` with `pip install vale` and then run
+`vale --config=vale/.vale.ini docs/`.

test_documentation.sh

-#!/bin/bash
-
-docker run -it --rm -v $(pwd):/docs sphinxdoc/sphinx:latest /bin/bash -c \
-"pip install sphinx_rtd_theme myst-parser;cd docs;make html"
-
-if [ ! -d ./vale/styles/proselint ] || [ ! -d ./vale/styles/Microsoft ]; then
-  docker run -it --rm -v $(pwd):/gap jdkato/vale:latest --config="/gap/vale/.vale.ini" sync
-fi
-
-docker run -it --rm -v $(pwd):/gap jdkato/vale:latest --config="/gap/vale/.vale.ini" /gap/build/html/_sources/

vale/.vale.ini

@@ -6,10 +6,7 @@ Vocab = geant-jargon, Sphinx
 
 Packages = proselint, Microsoft
 
-[formats]
-txt = md
-
-[*]
+[*.md]
 BasedOnStyles = Vale, proselint, Microsoft
 
 ; Found to be too intrusive
@@ -20,6 +17,3 @@ Microsoft.GeneralURL = NO
 proselint.Typography = warning
 ; Same applies for not using contractions
 Microsoft.Contractions = warning
-
-; Ignore the table of contents directive
-BlockIgnores = (?s) *(\x60\x60\x60{toctree}.*?\x60\x60\x60)