Use MkDocs for project documentation (casid#288)

* Markdown linting and a few uses of github notes

* Fix/Improve grammar issues

* docs: Move documentation to mkdocs structure

* docs: Ignore site generated folder

* ci: Add workflow to validate docs

* ci: Add workflow to publish docs

Only publish docs for tags.

* ci: Execute validate-docs workflow only on docs change

* ci: No need to run mvn tasks when on docs changes

* docs: Add link to hot-reloading

* docs: remove mkdocs-macros plugin

* docs: use teal color pallete

* docs: site wide description

* docs: add navigation progress indicator

* docs: Move spring boot starters docs to /docs directory

Keep the existing files so that they can point to the new docs.

* docs: Update docs references to point to the new location

* docs: move jsp converter docs to /docs

* docs: move jte-models docs to /docs

* dos: move jte-extension-api to /docs

* ci: Move publish-docs permissions to job level

* docs: a few minor formatting changes

* ci: Use GH Pages actions to publish the docs

* docs: Remove docs versioning

* ci: Allow to manually trigger the flow

* Try with published releases

* Some minor clean ups

.github/workflows/graalvm.yml

@@ -1,6 +1,17 @@
 name: Test native builds
 
-on: [push, pull_request]
+# No need to run when only the docs are changing. There is
+# a workflow to validate the docs.
+# https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#onpushpull_requestpull_request_targetpathspaths-ignore
+on:
+  pull_request:
+    paths-ignore:
+      - 'docs/**'
+      - 'mkdocs.yml'
+  push:
+    paths-ignore:
+      - 'docs/**'
+      - 'mkdocs.yml'
 
 jobs:
   build:

.github/workflows/maven.yml

@@ -1,6 +1,17 @@
 name: Test all JDKs on all OSes
 
-on: [push, pull_request]
+# No need to run when only the docs are changing. There is
+# a workflow to validate the docs.
+# https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#onpushpull_requestpull_request_targetpathspaths-ignore
+on:
+  pull_request:
+    paths-ignore:
+      - 'docs/**'
+      - 'mkdocs.yml'
+  push:
+    paths-ignore:
+      - 'docs/**'
+      - 'mkdocs.yml'
 
 jobs:
   build:

.github/workflows/publish-docs.yml

@@ -0,0 +1,67 @@
+name: Publish Docs
+
+on:
+  # Runs whenever there is a release/tag creation
+  release:
+    types: [ "published" ]
+
+  #  push:
+  #    tags:
+  #      - '[0-9]+.[0-9]+.[0-9]+'
+
+  # Allows to run this workflow manually from the Actions tab
+  workflow_dispatch:
+
+permissions:
+  # Checkout the project's code
+  contents: read
+  # Allow to deploy to gh-pages
+  pages: write
+  # To verify the deployment originates from an appropriate source
+  id-token: write
+
+# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
+# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v4
+        with:
+          python-version: 3.x
+      - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV
+      - uses: actions/cache@v3
+        with:
+          key: mkdocs-material-${{ env.cache_id }}
+          path: .cache
+          restore-keys: |
+            mkdocs-material-
+      # Keep the list of installed pip packages consistent with
+      # the list in validate-docs.yml.
+      - run: pip install mkdocs-material
+      - run: pip install mkdocs-awesome-pages-plugin
+      - run: pip install mkdocs-pom-parser-plugin
+      - name: Create new docs version
+        # `_site` is the default path expected by `actions/upload-pages-artifact` to
+        # find the static assets.
+        run: mkdocs build --site-dir _site
+      - name: Setup Pages
+        uses: actions/configure-pages@v3
+      - name: Upload Pages artifact
+        uses: actions/upload-pages-artifact@v2
+
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v2

.github/workflows/validate-docs.yml

@@ -0,0 +1,40 @@
+name: Validate docs
+
+# Only run workflow if the docs are changing.
+# https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#onpushpull_requestpull_request_targetpathspaths-ignore
+on:
+    pull_request:
+      paths:
+        - 'mkdocs.yml'
+        - 'docs/**'
+    push:
+      paths:
+        - 'mkdocs.yml'
+        - 'docs/**'
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v4
+        with:
+          python-version: 3.x
+      - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV
+      - uses: actions/cache@v3
+        with:
+          key: mkdocs-material-${{ env.cache_id }}
+          path: .cache
+          restore-keys: |
+            mkdocs-material-
+      # Keep the list of installed pip packages consistent with
+      # the list in publish-docs.yml.
+      - run: pip install mkdocs-material
+      - run: pip install mkdocs-awesome-pages-plugin
+      - run: pip install mkdocs-pom-parser-plugin
+      - name: Build docs
+        # https://www.mkdocs.org/user-guide/cli/#mkdocs-build
+        # --strict cause MkDocs to abort the build on any warnings.
+        # For example, broken internal links. More about validation
+        # here: https://www.mkdocs.org/user-guide/configuration/#validation.
+        run: mkdocs build --strict

.gitignore

@@ -116,3 +116,5 @@ Temporary Items
 .classpath
 bin/
 .factorypath
+
+site