From 0afe65c4269a4bad3b31db79351dccbff4080f1e Mon Sep 17 00:00:00 2001 From: Jeffrey Aven Date: Tue, 6 Oct 2026 16:34:48 +1100 Subject: [PATCH 1/3] docs: regenerate with @stackql/provider-utils 0.7.11 and the source repo link Bumps @stackql/provider-utils to 0.7.11, passes --source-project to the doc generation target and regenerates the markdown docs, so the provider summary links to the source repository. Co-Authored-By: Claude Fable 5.1 --- bin/generate-docs.mjs | 4 ++- bin/generate-docs.sh | 11 ++++++- package-lock.json | 68 ++++++++++++++++++++++++++++++++++--------- package.json | 2 +- website/docs/index.md | 1 + 5 files changed, 70 insertions(+), 16 deletions(-) diff --git a/bin/generate-docs.mjs b/bin/generate-docs.mjs index 4be9b84..fec1d6b 100644 --- a/bin/generate-docs.mjs +++ b/bin/generate-docs.mjs @@ -14,6 +14,7 @@ async function generateDocs() { const providerDir = getArg('--provider-dir'); const outputDir = getArg('--output-dir'); const providerDataDir = getArg('--provider-data-dir'); + const sourceProject = getArg('--source-project'); if (!providerName || !providerDir || !outputDir || !providerDataDir) { console.error('Error: Missing required arguments'); @@ -31,7 +32,8 @@ async function generateDocs() { providerName, providerDir, outputDir, - providerDataDir + providerDataDir, + sourceProject }); console.log('Documentation generated successfully:', result); diff --git a/bin/generate-docs.sh b/bin/generate-docs.sh index d375179..14d2696 100644 --- a/bin/generate-docs.sh +++ b/bin/generate-docs.sh @@ -6,6 +6,9 @@ set -e # Get the script directory for relative paths SCRIPT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )" REPO_ROOT="$( cd "$SCRIPT_DIR/.." && pwd )" +# Repository linked from the Provider Summary on the docs landing page +# (--source-project, provider-utils >= 0.7.11); override with --source-project. +SOURCE_PROJECT="${SOURCE_PROJECT:-https://github.com/stackql-registry/stackql-provider-openai}" # Parse command line arguments while [[ $# -gt 0 ]]; do @@ -26,6 +29,10 @@ while [[ $# -gt 0 ]]; do PROVIDER_DATA_DIR="$2" shift 2 ;; + --source-project) + SOURCE_PROJECT="$2" + shift 2 + ;; --help) echo "Usage: generate-docs.sh [OPTIONS]" echo "" @@ -34,6 +41,7 @@ while [[ $# -gt 0 ]]; do echo " --provider-dir DIR Provider directory path (default: $PROVIDER_DIR)" echo " --output-dir DIR Output directory for docs (default: $OUTPUT_DIR)" echo " --provider-data-dir DIR Provider data directory (default: $PROVIDER_DATA_DIR)" + echo " --source-project URL Repository URL linked from the provider summary (default: $SOURCE_PROJECT)" echo " --help Show this help message" exit 0 ;; @@ -52,7 +60,8 @@ node --experimental-modules "$SCRIPT_DIR/generate-docs.mjs" \ --provider-name "$PROVIDER_NAME" \ --provider-dir "$PROVIDER_DIR" \ --output-dir "$OUTPUT_DIR" \ - --provider-data-dir "$PROVIDER_DATA_DIR" + --provider-data-dir "$PROVIDER_DATA_DIR" \ + --source-project "$SOURCE_PROJECT" # Check if command succeeded if [ $? -ne 0 ]; then diff --git a/package-lock.json b/package-lock.json index 2d36f93..3677f7b 100644 --- a/package-lock.json +++ b/package-lock.json @@ -10,7 +10,7 @@ "dependencies": { "@apidevtools/swagger-parser": "^12.0.0", "@stackql/pgwire-lite": "^1.0.1", - "@stackql/provider-utils": "^0.7.6", + "@stackql/provider-utils": "^0.7.11", "js-yaml": "^4.1.0" }, "engines": { @@ -91,13 +91,37 @@ "integrity": "sha512-4JQNk+3mVzK3xh2rqd6RB4J46qUR19azEHBneZyTZM+c456qOrbbM/5xcR8huNCCcbVt7+UmizG6GuUvPvKUYg==", "license": "MIT" }, + "node_modules/@jsep-plugin/assignment": { + "version": "1.3.0", + "resolved": "https://registry.npmjs.org/@jsep-plugin/assignment/-/assignment-1.3.0.tgz", + "integrity": "sha512-VVgV+CXrhbMI3aSusQyclHkenWSAm95WaiKrMxRFam3JSUiIaQjoMIw2sEs/OX4XifnqeQUN4DYbJjlA8EfktQ==", + "license": "MIT", + "engines": { + "node": ">= 10.16.0" + }, + "peerDependencies": { + "jsep": "^0.4.0||^1.0.0" + } + }, + "node_modules/@jsep-plugin/regex": { + "version": "1.0.4", + "resolved": "https://registry.npmjs.org/@jsep-plugin/regex/-/regex-1.0.4.tgz", + "integrity": "sha512-q7qL4Mgjs1vByCaTnDFcBnV9HS7GVPJX5vyVoCgZHNSC9rjwIlmbXG5sUuorR5ndfHAIlJ8pVStxvjXHbNvtUg==", + "license": "MIT", + "engines": { + "node": ">= 10.16.0" + }, + "peerDependencies": { + "jsep": "^0.4.0||^1.0.0" + } + }, "node_modules/@stackql/deno-openapi-dereferencer": { "name": "@jsr/stackql__deno-openapi-dereferencer", - "version": "0.3.1", - "resolved": "https://npm.jsr.io/~/11/@jsr/stackql__deno-openapi-dereferencer/0.3.1.tgz", - "integrity": "sha512-7Ucdom3SYxvzp7VwzulQMe66E+1LeCZIprFQ70PwRPIUfL90bYNQDrLfe5L1WaB+X7StWdHmoFSFxoa9RDlN7w==", + "version": "0.3.2", + "resolved": "https://npm.jsr.io/~/11/@jsr/stackql__deno-openapi-dereferencer/0.3.2.tgz", + "integrity": "sha512-Qj5B0pl2Rsec+GHwGGIh9254AQfEplkD82HW9FEhQR+vZvzhEgF2Ap72hmdLq8rWOGV4soSnQ4sFYorE2pIT5Q==", "dependencies": { - "jsonpath-plus": "7.0.0" + "jsonpath-plus": "^10.3.0" } }, "node_modules/@stackql/pgwire-lite": { @@ -110,13 +134,13 @@ } }, "node_modules/@stackql/provider-utils": { - "version": "0.7.6", - "resolved": "https://registry.npmjs.org/@stackql/provider-utils/-/provider-utils-0.7.6.tgz", - "integrity": "sha512-1aa7xdVKoA9RppNIE/ojOTmc8k/I+glyKqAjZjTvcA87kyP7gmbMJPOdsX+LDFxSJ5xfslxTR+/ZZD3M5HZsiw==", + "version": "0.7.11", + "resolved": "https://registry.npmjs.org/@stackql/provider-utils/-/provider-utils-0.7.11.tgz", + "integrity": "sha512-yRy0nbWzI8IkAZlN2WCMxz/9pdD11EXTx85U+e6pQzIq61CtUpVLklW70Z4fMTTGwLa9nzLqWCNPS5+LBBY0+g==", "license": "MIT", "dependencies": { "@apidevtools/swagger-parser": "^10.1.1", - "@stackql/deno-openapi-dereferencer": "npm:@jsr/stackql__deno-openapi-dereferencer@^0.3.1", + "@stackql/deno-openapi-dereferencer": "npm:@jsr/stackql__deno-openapi-dereferencer@^0.3.2", "csv-parser": "^3.2.0", "js-yaml": "^4.1.0", "pluralize": "^8.0.0" @@ -357,6 +381,15 @@ "js-yaml": "bin/js-yaml.js" } }, + "node_modules/jsep": { + "version": "1.4.0", + "resolved": "https://registry.npmjs.org/jsep/-/jsep-1.4.0.tgz", + "integrity": "sha512-B7qPcEVE3NVkmSJbaYxvv4cHkVW7DQsZz13pUMrfS8z8Q/BuShN+gcTXrUlPiGqM2/t/EEaI030bpxMqY8gMlw==", + "license": "MIT", + "engines": { + "node": ">= 10.16.0" + } + }, "node_modules/json-schema-traverse": { "version": "1.0.0", "resolved": "https://registry.npmjs.org/json-schema-traverse/-/json-schema-traverse-1.0.0.tgz", @@ -364,12 +397,21 @@ "license": "MIT" }, "node_modules/jsonpath-plus": { - "version": "7.0.0", - "resolved": "https://registry.npmjs.org/jsonpath-plus/-/jsonpath-plus-7.0.0.tgz", - "integrity": "sha512-MH4UnrWrU1hJGVEyEyjvYgONkzNTO6Yol0nq18EMnUQ/ZC5cTuJheirXXIwu1b9mZ6t3XL0P79gPsu+zlTnDIQ==", + "version": "10.4.0", + "resolved": "https://registry.npmjs.org/jsonpath-plus/-/jsonpath-plus-10.4.0.tgz", + "integrity": "sha512-T92WWatJXmhBbKsgH/0hl+jxjdXrifi5IKeMY02DWggRxX0UElcbVzPlmgLTbvsPeW1PasQ6xE2Q75stkhGbsA==", "license": "MIT", + "dependencies": { + "@jsep-plugin/assignment": "^1.3.0", + "@jsep-plugin/regex": "^1.0.4", + "jsep": "^1.4.0" + }, + "bin": { + "jsonpath": "bin/jsonpath-cli.js", + "jsonpath-plus": "bin/jsonpath-cli.js" + }, "engines": { - "node": ">=12.0.0" + "node": ">=18.0.0" } }, "node_modules/kuler": { diff --git a/package.json b/package.json index 421f9ca..e15e390 100644 --- a/package.json +++ b/package.json @@ -22,7 +22,7 @@ "dependencies": { "@apidevtools/swagger-parser": "^12.0.0", "@stackql/pgwire-lite": "^1.0.1", - "@stackql/provider-utils": "^0.7.6", + "@stackql/provider-utils": "^0.7.11", "js-yaml": "^4.1.0" }, "keywords": [ diff --git a/website/docs/index.md b/website/docs/index.md index c5ed50b..20a0425 100644 --- a/website/docs/index.md +++ b/website/docs/index.md @@ -23,6 +23,7 @@ The OpenAI platform surface available to standard API keys - models, files, fine total services: __11__ total resources: __37__ +source project: __[stackql-provider-openai](https://github.com/stackql-registry/stackql-provider-openai)__ ::: From 4ff7df96e2cb96c224630a160911533d88430a11 Mon Sep 17 00:00:00 2001 From: Jeffrey Aven Date: Tue, 6 Oct 2026 16:34:49 +1100 Subject: [PATCH 2/3] website: add the Back to StackQL Docs sidebar link Opens the docs sidebar with a link to /stackqldocs, the redirect to the main stackql.io docs, matching the query library site and the provider template. Styled by the new .sidebar-back-link rules in the site stylesheet. No generated docs or dependencies change. Co-Authored-By: Claude Fable 5.1 --- website/sidebars.js | 13 +++++++++++++ website/src/css/global.css | 22 +++++++++++++++++++++- 2 files changed, 34 insertions(+), 1 deletion(-) diff --git a/website/sidebars.js b/website/sidebars.js index f719984..fe6cbb3 100644 --- a/website/sidebars.js +++ b/website/sidebars.js @@ -2,6 +2,19 @@ import { providerTitle } from './provider.js'; const sidebars = { mainSidebar: [ + // Way back to the main stackql.io docs, as on the query library site. + // '/stackqldocs' is a shared-config redirect route (registered on this + // site by the vendored redirects plugin) that forwards to + // https://stackql.io/, so the link renders as internal - no external-link + // icon - and the broken-link checker validates it. The arrow and the + // divider come from the .sidebar-back-link rules in src/css/global.css. + { + type: 'link', + label: 'Back to StackQL Docs', + href: '/stackqldocs', + className: 'sidebar-back-link', + }, + // '/providers' is likewise a shared redirect, to https://stackql.io/providers. { type: 'link', label: 'All Providers', href: '/providers' }, { type: 'category', diff --git a/website/src/css/global.css b/website/src/css/global.css index 3e50218..0b80357 100644 --- a/website/src/css/global.css +++ b/website/src/css/global.css @@ -284,4 +284,24 @@ div:has(> .vhsImage) { .navbar__logo img[src$='stackql-registry-logo-white.svg'] { content: url('/img/stackql-registry-logo-white-mobile.svg'); } -} \ No newline at end of file +} + +/* +* sidebar: back link to the main stackql.io docs (the first item in +* sidebars.js). Same treatment as the query library site: bold label, +* leading arrow drawn here so the label stays plain text, divider below. +*/ +.sidebar-back-link { + border-bottom: 1px solid var(--ifm-color-emphasis-300); + padding-bottom: 0.5rem; + margin-bottom: 0.5rem !important; +} + +.sidebar-back-link .menu__link { + font-weight: 600; +} + +.sidebar-back-link .menu__link::before { + content: '\2190'; + margin-right: 0.5rem; +} From e078364c0f4c51340013f6a1a01e17d20f263683 Mon Sep 17 00:00:00 2001 From: Jeffrey Aven Date: Tue, 6 Oct 2026 18:46:26 +1100 Subject: [PATCH 3/3] docs: bump @stackql/provider-utils to 0.7.12 Keeps the doc generation dependency on the current release. 0.7.12 only changes the generate-docs-v2 index page (Markdown hard breaks in the Provider Summary); this provider uses the v1 generator, whose output is unchanged, so the regenerated docs are identical. Co-Authored-By: Claude Fable 5.1 --- package-lock.json | 8 ++++---- package.json | 2 +- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/package-lock.json b/package-lock.json index 3677f7b..dc2358c 100644 --- a/package-lock.json +++ b/package-lock.json @@ -10,7 +10,7 @@ "dependencies": { "@apidevtools/swagger-parser": "^12.0.0", "@stackql/pgwire-lite": "^1.0.1", - "@stackql/provider-utils": "^0.7.11", + "@stackql/provider-utils": "^0.7.12", "js-yaml": "^4.1.0" }, "engines": { @@ -134,9 +134,9 @@ } }, "node_modules/@stackql/provider-utils": { - "version": "0.7.11", - "resolved": "https://registry.npmjs.org/@stackql/provider-utils/-/provider-utils-0.7.11.tgz", - "integrity": "sha512-yRy0nbWzI8IkAZlN2WCMxz/9pdD11EXTx85U+e6pQzIq61CtUpVLklW70Z4fMTTGwLa9nzLqWCNPS5+LBBY0+g==", + "version": "0.7.12", + "resolved": "https://registry.npmjs.org/@stackql/provider-utils/-/provider-utils-0.7.12.tgz", + "integrity": "sha512-cwlnLkW/AZ86YVthU/HmVDVlwLHsuJtiCx+w0peqO7t/NpsgLsUneH5vG2PPt+yPv3euZeQg1HeO7NOAgDQdBw==", "license": "MIT", "dependencies": { "@apidevtools/swagger-parser": "^10.1.1", diff --git a/package.json b/package.json index e15e390..5fbbe19 100644 --- a/package.json +++ b/package.json @@ -22,7 +22,7 @@ "dependencies": { "@apidevtools/swagger-parser": "^12.0.0", "@stackql/pgwire-lite": "^1.0.1", - "@stackql/provider-utils": "^0.7.11", + "@stackql/provider-utils": "^0.7.12", "js-yaml": "^4.1.0" }, "keywords": [