✨ Fix links in OpenAPI description nodes (#3598)

Signed-off-by: Alexandre Franke <alexandre.franke@matrix.org>

.github/workflows/main.yml

@@ -39,18 +39,45 @@ jobs:
         run: |
           /env/bin/python scripts/check-event-schema-examples.py
 
+  calculate-baseurl:
+    name: "⚙️ Calculate baseURL for later jobs"
+    runs-on: ubuntu-latest
+    outputs:
+      baseURL: "${{ steps.set-baseurl.outputs.baseURL }}"
+    steps:
+      # For PRs, set the baseURL to `/`.
+      # For releases, set the baseURL to `/$tag` (eg: `/v1.2`).
+      # Otherwise, set it to `/unstable`.
+      - name: "⚙️ Calculate baseURL"
+        id: set-baseurl
+        # Double brackets on the elif to avoid auto-escaping refs/tags/* because we need
+        # the asterisk matching behaviour, not the literal string.
+        run: |
+          if [ "${GITHUB_EVENT_NAME}" == "pull_request" ]; then
+              echo ::set-output name=baseURL::/
+          elif [[ "${GITHUB_REF}" == refs/tags/* ]]; then
+              echo ::set-output name=baseURL::"/${GITHUB_REF/refs\/tags\//}"
+          else
+              echo ::set-output name=baseURL::/unstable
+          fi
+
   build-openapi:
     name: "🐍 Build OpenAPI definitions"
     runs-on: ubuntu-latest
     container: "python:3.9"
+    needs: [calculate-baseurl]
     steps:
       - name: "📥 Source checkout"
         uses: actions/checkout@v2
       - name: "📦 Asset creation"
         run: |
+          mkdir -p assets
           python3 -m venv env && . env/bin/activate
           pip install -r scripts/requirements.txt
-          scripts/generate-matrix-org-assets
+          scripts/dump-swagger.py \
+            --base-url "${{ needs.calculate-baseurl.outputs.baseURL }}" \
+            -o assets/spec/client_server/api.json
+          tar -czf assets.tar.gz assets
       - name: "📤 Artifact upload"
         uses: actions/upload-artifact@v2
         with:
@@ -60,7 +87,7 @@ jobs:
   build-spec:
     name: "📖 Build the spec"
     runs-on: ubuntu-latest
-    needs: [build-openapi]
+    needs: [calculate-baseurl, build-openapi]
     steps:
       - name: "➕ Setup Node"
         uses: actions/setup-node@v2
@@ -79,25 +106,8 @@ jobs:
         run: |
           npm i
           npm run get-proposals
-
-      # For PRs, set the baseURL to `/`.
-      # For releases, set the baseURL to `/$tag` (eg: `/v1.2`).
-      # Otherwise, set it to `/unstable`.
-      - name: "⚙️ Calculate baseURL"
-        id: set-baseurl
-        # Double brackets on the elif to avoid auto-escaping refs/tags/* because we need
-        # the asterisk matching behaviour, not the literal string.
-        run: |
-          if [ "${GITHUB_EVENT_NAME}" == "pull_request" ]; then
-              echo ::set-output name=baseURL::/
-          elif [[ "${GITHUB_REF}" == refs/tags/* ]]; then
-              echo ::set-output name=baseURL::"/${GITHUB_REF/refs\/tags\//}"
-          else
-              echo ::set-output name=baseURL::/unstable
-          fi
-
       - name: "⚙️ hugo"
-        run: hugo --baseURL "${{ steps.set-baseurl.outputs.baseURL }}" -d "spec"
+        run: hugo --baseURL "${{ needs.calculate-baseurl.outputs.baseURL }}" -d "spec"
 
       # We manually copy the spec OpenAPI definition JSON to the website tree
       # to make it available to the world in a canonical place:

scripts/dump-swagger.py

@@ -53,10 +53,39 @@ def resolve_references(path, schema):
     else:
         return schema
 
+def prefix_absolute_path_references(text, base_url):
+    """Adds base_url to absolute-path references.
+
+    Markdown links in descriptions may be absolute-path references.
+    These won’t work when the spec is not hosted at the root, such as
+    https://spec.matrix.org/latest/
+    This turns all `[foo](/bar)` found in text into
+    `[foo](https://spec.matrix.org/latest/bar)`, with
+    base_url = 'https://spec.matrix.org/latest/'
+    """
+    return text.replace("](/", "]({}/".format(base_url))
+
+def edit_links(node, base_url):
+    """Finds description nodes and makes any links in them absolute."""
+    if isinstance(node, dict):
+        for key in node:
+            if isinstance(node[key], str):
+                node[key] = prefix_absolute_path_references(node[key], base_url)
+            else:
+                edit_links(node[key], base_url)
+    elif isinstance(node, list):
+        for item in node:
+            edit_links(item, base_url)
 
 parser = argparse.ArgumentParser(
     "dump-swagger.py - assemble the Swagger specs into a single JSON file"
 )
+parser.add_argument(
+    "--base-url", "-b",
+    default="https://spec.matrix.org/unstable/",
+    help="""The base URL to prepend to links in descriptions. Default:
+    %(default)s""",
+)
 parser.add_argument(
     "--client_release", "-c", metavar="LABEL",
     default="unstable",
@@ -78,6 +107,8 @@ match = re.match("^(r\d+)(\.\d+)*$", major_version)
 if match:
     major_version = match.group(1)
 
+base_url = args.base_url.rstrip("/")
+
 logging.basicConfig()
 
 output = {
@@ -130,6 +161,8 @@ for filename in os.listdir(cs_api_dir):
                         output["paths"][path] = {}
                     output["paths"][path][method] = spec
 
+edit_links(output, base_url)
+
 print("Generating %s" % output_file)
 
 try:

scripts/generate-matrix-org-assets

@@ -1,15 +0,0 @@
-#!/bin/sh
-#
-# generate a tarball of assets suitable for the matrix.org site
-
-set -e
-
-cd `dirname $0`/..
-
-mkdir -p assets
-
-# and the swagger
-./scripts/dump-swagger.py -o assets/spec/client_server/api.json
-
-# create a tarball of the assets.
-tar -czf assets.tar.gz assets