Add preview link

.gitlab-ci.yml

@@ -32,11 +32,31 @@ build:
 
   script:
     - poetry run make html
+    # for some reason, we need to insert an additional /-/ between base url and the project path for this to work
+    - echo "BUILD_JOB_ID=${CI_JOB_ID}" >> deploy.env
+    - echo "ENVIRONMENT_URL=${CI_PAGES_URL}" | sed -e "s|$CI_PAGES_DOMAIN|${CI_PAGES_DOMAIN}/-|"  >> deploy.env
 
   artifacts:
     paths:
       - build/html
+    expose_as: "Rendered Documentation"
+    reports:
+      dotenv: deploy.env
 
+deploy-mr-preview:
+  stage: deploy
+  rules:
+    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
+  needs:
+    - job: build
+      artifacts: true
+
+  script:
+    - echo "Using ${ENVIRONMENT_URL} to host documentation"
+
+  environment:
+    name: "review-docs-mr-${CI_MERGE_REQUEST_IID}"
+    url: ${ENVIRONMENT_URL}/-/jobs/${BUILD_JOB_ID}/artifacts/build/html/index.html
 
 
 # actual deployment to gitlab pages, only on main