use markdown links in top-level readme and add docs rebuild downstream workflow

.github/workflows/trigger-docs-rebuild.yml

@@ -0,0 +1,66 @@
+name: Trigger docs rebuild
+
+# When Markdown sources change, rebuild the published documentation site by dispatching the sphinx.yml
+# workflow in the downstream openads-project/openads-project.github.io repository. Pushes to main also
+# deploy the result to GitHub Pages; pushes to other branches only build the docs (to validate them).
+on:
+  push:
+    branches:
+      - '**'
+    paths:
+      - 'README.md'
+      - 'docs/**.md'
+  workflow_dispatch:
+
+permissions: {}
+
+jobs:
+  trigger-docs-rebuild:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Dispatch sphinx.yml in openads-project.github.io
+        env:
+          # PAT/App token with actions read+write on the downstream repo (dispatch the run and wait on it).
+          GH_TOKEN: ${{ secrets.DOCS_DISPATCH_TOKEN }}
+          # Deploy only when the change landed on main; other branches trigger a build-only run.
+          DEPLOY: ${{ github.ref == 'refs/heads/main' }}
+          # The branch that triggered this run, so the downstream build checks out the same branch of the
+          # openadstack submodule and builds the docs from exactly these changes.
+          OPENADSTACK_REF: ${{ github.ref_name }}
+          DOWNSTREAM_REPO: openads-project/openads-project.github.io
+          DOWNSTREAM_REF: main
+        run: |
+          set -eo pipefail
+
+          # Note the time just before dispatching so we can identify the run we create - workflow_dispatch
+          # does not return a run id.
+          since="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
+
+          gh workflow run sphinx.yml \
+            --repo "${DOWNSTREAM_REPO}" \
+            --ref "${DOWNSTREAM_REF}" \
+            --field deploy="${DEPLOY}" \
+            --field openadstack_ref="${OPENADSTACK_REF}"
+
+          # The run is created asynchronously, so poll for the newest sphinx.yml workflow_dispatch run on the
+          # target ref that started at or after the dispatch time.
+          run_id=""
+          for _ in $(seq 1 12); do
+            sleep 5
+            run_id="$(gh run list --repo "${DOWNSTREAM_REPO}" --workflow sphinx.yml \
+              --event workflow_dispatch --branch "${DOWNSTREAM_REF}" \
+              --json databaseId,createdAt \
+              --jq "[.[] | select(.createdAt >= \"${since}\")] | max_by(.createdAt) | .databaseId // empty")"
+            if [ -n "${run_id}" ]; then
+              break
+            fi
+          done
+
+          if [ -z "${run_id}" ]; then
+            echo "::error::Could not locate the dispatched ${DOWNSTREAM_REPO} run to wait on."
+            exit 1
+          fi
+
+          echo "Waiting on downstream run ${run_id} (${DOWNSTREAM_REPO} @ ${DOWNSTREAM_REF})"
+          # --exit-status makes this step (and the job) fail if the downstream run concludes unsuccessfully.
+          gh run watch "${run_id}" --repo "${DOWNSTREAM_REPO}" --exit-status

README.md

@@ -11,7 +11,7 @@
 
 OpenADStack bundles reusable OpenADServices into a Docker Compose based reference stack. It supports different deployment compositions, from real-world automated-driving research with the [karl. research vehicle](https://karl.ac/) to lightweight and repeatable simulation tests in [OpenADSim](https://openads-project.github.io/openadsim/openadsim.html).
 
-**🚀 [Quick Start](#quick-start)** | **🏗️ [Architecture](#architecture)** | **📝 [Documentation](#documentation)** | **🙏 [Acknowledgements](#acknowledgements)**
+**🚀 [Quick Start](#-quick-start)** | **📐 [Architecture](#-architecture)** | **📝 [Documentation](#-documentation)** | **🙏 [Acknowledgements](#-acknowledgements)**
 
 > [!NOTE]
 > This repository is part of [***OpenADS***](https://github.com/openads-project), the *Open Automated Driving Systems* project. *OpenADS* and its modules have been initiated and are currently being maintained by the [**Institute for Automotive Engineering (ika) at RWTH Aachen University**](https://www.ika.rwth-aachen.de/de/).
@@ -22,8 +22,6 @@ OpenADStack bundles reusable OpenADServices into a Docker Compose based referenc
   <em>Watch the preview above or <a href="https://www.youtube.com/watch?v=B0Lnu-1w9KE">open the full video on YouTube</a>.</em>
 </div>
 
-<a name="quick-start"></a>
-
 ## 🚀 Quick Start
 
 > [!NOTE]
@@ -59,9 +57,7 @@ OpenADStack is usually part of a larger deployment composition, for example with
   docker compose down
   ```
 
-<a name="architecture"></a>
-
-## 🏗️ Architecture
+## 📐 Architecture
 
 OpenADStack is an L4 automated driving software stack built on ROS 2. It aims to enable suitably equipped vehicles to operate in traffic without human intervention.
 
@@ -83,8 +79,6 @@ The following image shows the so-called *A Model*, a functional reference archit
 
 </div>
 
-<a name="documentation"></a>
-
 ## 📝 Documentation
 
 The documentation contains:
@@ -94,8 +88,6 @@ The documentation contains:
 - [Integration Architecture](./docs/integration-architecture.md)
 - [Deployment Composition](./docs/deployment-composition.md)
 
-<a name="acknowledgements"></a>
-
 ## 🙏 Acknowledgements
 
 ### Citation