From b55cc15772c162dd7bcc1c6d59035d89601fb1f8 Mon Sep 17 00:00:00 2001 From: Alexandre Franke Date: Tue, 28 Dec 2021 18:14:44 +0100 Subject: [PATCH] =?UTF-8?q?=E2=9C=A8=20Fix=20links=20in=20OpenAPI=20descri?= =?UTF-8?q?ption=20nodes=20(#3598)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Alexandre Franke --- .github/workflows/main.yml | 52 ++++++++++++++++++------------ scripts/dump-swagger.py | 33 +++++++++++++++++++ scripts/generate-matrix-org-assets | 15 --------- 3 files changed, 64 insertions(+), 36 deletions(-) delete mode 100755 scripts/generate-matrix-org-assets diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml index a8dfff33..4e3edf82 100644 --- a/.github/workflows/main.yml +++ b/.github/workflows/main.yml @@ -38,19 +38,46 @@ jobs: - name: "πŸ”Ž Run validator" 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: diff --git a/scripts/dump-swagger.py b/scripts/dump-swagger.py index 8b594eef..c799e100 100755 --- a/scripts/dump-swagger.py +++ b/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: diff --git a/scripts/generate-matrix-org-assets b/scripts/generate-matrix-org-assets deleted file mode 100755 index ea33b9ff..00000000 --- a/scripts/generate-matrix-org-assets +++ /dev/null @@ -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