From 0b660d3c5824324e212adbb9aba19e29abf83231 Mon Sep 17 00:00:00 2001 From: Terry Sutton Date: Thu, 15 Dec 2022 11:52:00 -0330 Subject: [PATCH] Add CLI and API specs to search results --- apps/docs/lib/refGenerator/helpers.ts | 2 +- apps/docs/package.json | 2 +- apps/docs/public/sitemap.xml | 426 +++++++++--------- .../{build-search.js => build-search.ts} | 105 +---- apps/docs/scripts/files/api.ts | 43 ++ apps/docs/scripts/files/cli.ts | 43 ++ apps/docs/scripts/files/client-libs.ts | 57 +++ apps/docs/scripts/helpers.ts | 9 + apps/docs/scripts/tsconfig.json | 15 + 9 files changed, 407 insertions(+), 295 deletions(-) rename apps/docs/scripts/{build-search.js => build-search.ts} (60%) create mode 100644 apps/docs/scripts/files/api.ts create mode 100644 apps/docs/scripts/files/cli.ts create mode 100644 apps/docs/scripts/files/client-libs.ts create mode 100644 apps/docs/scripts/helpers.ts create mode 100644 apps/docs/scripts/tsconfig.json diff --git a/apps/docs/lib/refGenerator/helpers.ts b/apps/docs/lib/refGenerator/helpers.ts index ed8f18f5e4e..77a7aa16755 100644 --- a/apps/docs/lib/refGenerator/helpers.ts +++ b/apps/docs/lib/refGenerator/helpers.ts @@ -1,4 +1,4 @@ -import { TsDoc } from '~/generator/legacy/definitions' +import { TsDoc } from '../../generator/legacy/definitions' import { values, mapValues } from 'lodash' import { OpenAPIV3 } from 'openapi-types' diff --git a/apps/docs/package.json b/apps/docs/package.json index 4c40db4e3d1..2abc71adb53 100644 --- a/apps/docs/package.json +++ b/apps/docs/package.json @@ -8,7 +8,7 @@ "start": "next start", "lint": "next lint", "build:sitemap": "node ./internals/generate-sitemap.mjs", - "postbuild": "node ./scripts/build-search.js && node ./internals/generate-sitemap.mjs", + "postbuild": "ts-node ./scripts/build-search.ts && node ./internals/generate-sitemap.mjs", "generate:all": "npm-run-all --parallel gen:api gen:cli gen:gotrue gen:storage gen:supabase-dart:v0 gen:supabase-dart:v1 gen:supabase-js:v1 gen:supabase-js:v2 gen:realtime", "gen:api": "npm-run-all gen:api:usage", "gen:api:usage": "ts-node ./generator/index.ts gen --type api --url https://api.supabase.com --input ../../spec/transforms/api_v0_openapi_deparsed.json --output ./docs/reference/api/generated/usage.mdx", diff --git a/apps/docs/public/sitemap.xml b/apps/docs/public/sitemap.xml index bbf3b19ddf2..056ae9301cd 100644 --- a/apps/docs/public/sitemap.xml +++ b/apps/docs/public/sitemap.xml @@ -48,6 +48,24 @@ 0.5 + + https://supabase.com/docs/new/auth + weekly + 0.5 + + + + https://supabase.com/docs/handbook/contributing + weekly + 0.5 + + + + https://supabase.com/docs/handbook/introduction + weekly + 0.5 + + https://supabase.com/docs/guides/api weekly @@ -115,19 +133,7 @@ - https://supabase.com/docs/handbook/contributing - weekly - 0.5 - - - - https://supabase.com/docs/handbook/introduction - weekly - 0.5 - - - - https://supabase.com/docs/new/auth + https://supabase.com/docs/reference/index weekly 0.5 @@ -139,7 +145,31 @@ - https://supabase.com/docs/reference/index + https://supabase.com/docs/learn/auth-deep-dive/auth-deep-dive-jwts + weekly + 0.5 + + + + https://supabase.com/docs/learn/auth-deep-dive/auth-google-oauth + weekly + 0.5 + + + + https://supabase.com/docs/learn/auth-deep-dive/auth-gotrue + weekly + 0.5 + + + + https://supabase.com/docs/learn/auth-deep-dive/auth-policies + weekly + 0.5 + + + + https://supabase.com/docs/learn/auth-deep-dive/auth-row-level-security weekly 0.5 @@ -151,37 +181,7 @@ - https://supabase.com/docs/guides/functions/auth - weekly - 0.5 - - - - https://supabase.com/docs/guides/functions/best-practices - weekly - 0.5 - - - - https://supabase.com/docs/guides/functions/cicd-workflow - weekly - 0.5 - - - - https://supabase.com/docs/guides/functions/quickstart - weekly - 0.5 - - - - https://supabase.com/docs/guides/getting-started/architecture - weekly - 0.5 - - - - https://supabase.com/docs/guides/getting-started/features + https://supabase.com/docs/new/auth/auth-login weekly 0.5 @@ -252,6 +252,42 @@ 0.5 + + https://supabase.com/docs/guides/getting-started/architecture + weekly + 0.5 + + + + https://supabase.com/docs/guides/getting-started/features + weekly + 0.5 + + + + https://supabase.com/docs/guides/functions/auth + weekly + 0.5 + + + + https://supabase.com/docs/guides/functions/best-practices + weekly + 0.5 + + + + https://supabase.com/docs/guides/functions/cicd-workflow + weekly + 0.5 + + + + https://supabase.com/docs/guides/functions/quickstart + weekly + 0.5 + + https://supabase.com/docs/guides/database/arrays weekly @@ -480,6 +516,24 @@ 0.5 + + https://supabase.com/docs/guides/realtime/postgres-changes + weekly + 0.5 + + + + https://supabase.com/docs/guides/realtime/quickstart + weekly + 0.5 + + + + https://supabase.com/docs/guides/realtime/rate-limits + weekly + 0.5 + + https://supabase.com/docs/guides/platform/access-control weekly @@ -552,42 +606,6 @@ 0.5 - - https://supabase.com/docs/guides/realtime/postgres-changes - weekly - 0.5 - - - - https://supabase.com/docs/guides/realtime/quickstart - weekly - 0.5 - - - - https://supabase.com/docs/guides/realtime/rate-limits - weekly - 0.5 - - - - https://supabase.com/docs/guides/resources/glossary - weekly - 0.5 - - - - https://supabase.com/docs/guides/resources/self-hosting - weekly - 0.5 - - - - https://supabase.com/docs/guides/resources/supabase-cli - weekly - 0.5 - - https://supabase.com/docs/guides/storage/access-control weekly @@ -619,145 +637,19 @@ - https://supabase.com/docs/new/auth/auth-login + https://supabase.com/docs/guides/resources/glossary weekly 0.5 - https://supabase.com/docs/learn/auth-deep-dive/auth-deep-dive-jwts + https://supabase.com/docs/guides/resources/self-hosting weekly 0.5 - https://supabase.com/docs/learn/auth-deep-dive/auth-google-oauth - weekly - 0.5 - - - - https://supabase.com/docs/learn/auth-deep-dive/auth-gotrue - weekly - 0.5 - - - - https://supabase.com/docs/learn/auth-deep-dive/auth-policies - weekly - 0.5 - - - - https://supabase.com/docs/learn/auth-deep-dive/auth-row-level-security - weekly - 0.5 - - - - https://supabase.com/docs/guides/functions/examples/og-image - weekly - 0.5 - - - - https://supabase.com/docs/guides/getting-started/quickstarts/nextjs - weekly - 0.5 - - - - https://supabase.com/docs/guides/getting-started/quickstarts/nuxtjs - weekly - 0.5 - - - - https://supabase.com/docs/guides/getting-started/quickstarts/reactjs - weekly - 0.5 - - - - https://supabase.com/docs/guides/getting-started/tutorials/with-angular - weekly - 0.5 - - - - https://supabase.com/docs/guides/getting-started/tutorials/with-expo - weekly - 0.5 - - - - https://supabase.com/docs/guides/getting-started/tutorials/with-flutter - weekly - 0.5 - - - - https://supabase.com/docs/guides/getting-started/tutorials/with-ionic-angular - weekly - 0.5 - - - - https://supabase.com/docs/guides/getting-started/tutorials/with-ionic-react - weekly - 0.5 - - - - https://supabase.com/docs/guides/getting-started/tutorials/with-ionic-vue - weekly - 0.5 - - - - https://supabase.com/docs/guides/getting-started/tutorials/with-nextjs - weekly - 0.5 - - - - https://supabase.com/docs/guides/getting-started/tutorials/with-nuxt-3 - weekly - 0.5 - - - - https://supabase.com/docs/guides/getting-started/tutorials/with-react - weekly - 0.5 - - - - https://supabase.com/docs/guides/getting-started/tutorials/with-redwoodjs - weekly - 0.5 - - - - https://supabase.com/docs/guides/getting-started/tutorials/with-solidjs - weekly - 0.5 - - - - https://supabase.com/docs/guides/getting-started/tutorials/with-svelte - weekly - 0.5 - - - - https://supabase.com/docs/guides/getting-started/tutorials/with-sveltekit - weekly - 0.5 - - - - https://supabase.com/docs/guides/getting-started/tutorials/with-vue-3 + https://supabase.com/docs/guides/resources/supabase-cli weekly 0.5 @@ -913,19 +805,25 @@ - https://supabase.com/docs/guides/platform/sso/azure + https://supabase.com/docs/guides/getting-started/quickstarts/nextjs weekly 0.5 - https://supabase.com/docs/guides/platform/sso/gsuite + https://supabase.com/docs/guides/getting-started/quickstarts/nuxtjs weekly 0.5 - https://supabase.com/docs/guides/platform/sso/okta + https://supabase.com/docs/guides/getting-started/quickstarts/reactjs + weekly + 0.5 + + + + https://supabase.com/docs/guides/functions/examples/og-image weekly 0.5 @@ -966,6 +864,108 @@ 0.5 + + https://supabase.com/docs/guides/getting-started/tutorials/with-angular + weekly + 0.5 + + + + https://supabase.com/docs/guides/getting-started/tutorials/with-expo + weekly + 0.5 + + + + https://supabase.com/docs/guides/getting-started/tutorials/with-flutter + weekly + 0.5 + + + + https://supabase.com/docs/guides/getting-started/tutorials/with-ionic-angular + weekly + 0.5 + + + + https://supabase.com/docs/guides/getting-started/tutorials/with-ionic-react + weekly + 0.5 + + + + https://supabase.com/docs/guides/getting-started/tutorials/with-ionic-vue + weekly + 0.5 + + + + https://supabase.com/docs/guides/getting-started/tutorials/with-nextjs + weekly + 0.5 + + + + https://supabase.com/docs/guides/getting-started/tutorials/with-nuxt-3 + weekly + 0.5 + + + + https://supabase.com/docs/guides/getting-started/tutorials/with-react + weekly + 0.5 + + + + https://supabase.com/docs/guides/getting-started/tutorials/with-redwoodjs + weekly + 0.5 + + + + https://supabase.com/docs/guides/getting-started/tutorials/with-solidjs + weekly + 0.5 + + + + https://supabase.com/docs/guides/getting-started/tutorials/with-svelte + weekly + 0.5 + + + + https://supabase.com/docs/guides/getting-started/tutorials/with-sveltekit + weekly + 0.5 + + + + https://supabase.com/docs/guides/getting-started/tutorials/with-vue-3 + weekly + 0.5 + + + + https://supabase.com/docs/guides/platform/sso/azure + weekly + 0.5 + + + + https://supabase.com/docs/guides/platform/sso/gsuite + weekly + 0.5 + + + + https://supabase.com/docs/guides/platform/sso/okta + weekly + 0.5 + + https://supabase.com/docs/guides/resources/migrating-to-supabase/firebase-auth weekly diff --git a/apps/docs/scripts/build-search.js b/apps/docs/scripts/build-search.ts similarity index 60% rename from apps/docs/scripts/build-search.js rename to apps/docs/scripts/build-search.ts index 3ba6d1c8f9e..1fdc4e18a88 100644 --- a/apps/docs/scripts/build-search.js +++ b/apps/docs/scripts/build-search.ts @@ -1,84 +1,21 @@ -const fs = require('fs') -const crypto = require('crypto') -const path = require('path') -const matter = require('gray-matter') -const dotenv = require('dotenv') -const algoliasearch = require('algoliasearch/lite') -const { isEmpty } = require('lodash') -const yaml = require('js-yaml') -const commonLibSections = require('../../../spec/common-client-libs-sections.json') +import fs from 'fs' +import crypto from 'crypto' +import path from 'path' +import matter from 'gray-matter' +import dotenv from 'dotenv' +import algoliasearch from 'algoliasearch/lite' +import { isEmpty } from 'lodash' -function flattenSections(sections) { - var a = [] - for (var i = 0; i < sections.length; i++) { - if (sections[i].id) { - // only push a section that has an id - // these are reserved for sidebar subtitles - a.push(sections[i]) - } - if (sections[i].items) { - // if there are subitems, loop through - a = a.concat(flattenSections(sections[i].items)) - } - } - return a -} +// search objects +import { generateClientLibSearchObjects } from './files/client-libs' +import { generateAPISearchObjects } from './files/api' +import { generateCLISearchObjects } from './files/cli' -const clientLibFiles = [ - { fileName: 'supabase_js_v2', label: 'javascript', version: 'v2', versionSlug: false }, - { fileName: 'supabase_js_v1', label: 'javascript', version: 'v1', versionSlug: true }, - { fileName: 'supabase_dart_v1', label: 'dart', version: 'v1', versionSlug: false }, - { fileName: 'supabase_dart_v0', label: 'dart', version: 'v0', versionSlug: true }, -] - -const nameMap = { - api: 'Management API', - cli: 'Supabase CLI', - auth: 'Auth Server', - storage: 'Storage Server', - postgres: 'Postgres', - dart: 'Supabase Flutter Library', - javascript: 'Supabase JavaScript Library', -} - -const flatCommonLibSections = flattenSections(commonLibSections) - -// loop through each spec file, find the correspending entry in the common file and grab the title / description / slug -let clientLibSearchObjects = [] - -clientLibFiles.map((file) => { - const specs = yaml.load(fs.readFileSync(`../../spec/${file.fileName}.yml`, 'utf8')) - - //take each function id, find it in the commonLibSections file and return { id, title, slug, description, } - specs.functions.map((fn) => { - const item = flatCommonLibSections.find((section) => section.id === fn.id) - if (item) { - const object = clientLibSearchObjects.push({ - objectID: crypto.randomUUID(), - id: item.id, - title: item.title, - description: item.title, - url: `/reference/${file.label}/${file.versionSlug ? file.version + '/' : ''}${item.slug}`, - source: 'reference', - pageContent: '', - category: item.product, - version: file.version, - type: 'lvl2', - hierarchy: { - lvl0: 'References', - lvl1: `${nameMap[file.label]} ${file.version}`, - lvl2: item.title, - lvl3: file.version, - lvl4: null, - lvl5: null, - lvl6: null, - }, - }) - return object - } - }) -}) +const cliObjects = generateCLISearchObjects() +const apiObjects = generateAPISearchObjects() +const clientLibSearchObjects = generateClientLibSearchObjects() +// @ts-ignore // The properties of the searchObject that are specifically read // by DocSearch are "type" and "hierarchy". The rest, though saved into Algolia (which we // can potentially use to craft more nuanced search experiences) are not used by DocSearch @@ -97,6 +34,7 @@ const ignoredFiles = [ async function walk(dir) { let files = await fs.promises.readdir(dir) + //@ts-ignore files = await Promise.all( files.map(async (file) => { const filePath = path.join(dir, file) @@ -131,7 +69,7 @@ async function walk(dir) { const guidePages = (await walk('pages')).filter((slug) => !ignoredFiles.includes(slug)) - // generate search objects for guide pages + // generate search objects for mdx guide pages const guidePagesearchObjects = guidePages .map((slug) => { let id, title, description @@ -196,13 +134,20 @@ async function walk(dir) { .filter((object) => !object.url.endsWith('/index')) .filter((object) => !object.url.endsWith('/.gitkeep')) - const combinedSearchObjects = guidePagesearchObjects.concat(clientLibSearchObjects) + const combinedSearchObjects = guidePagesearchObjects.concat( + clientLibSearchObjects, + apiObjects, + cliObjects + ) + //@ts-ignore await index.clearObjects() console.log(`Successfully cleared records from ${indexName}`) + //@ts-ignore const algoliaResponse = await index.saveObjects(combinedSearchObjects) + //@ts-ignore console.log(`Successfully saved ${algoliaResponse.objectIDs.length} records into ${indexName}.`) } catch (error) { console.log('Error:', error) diff --git a/apps/docs/scripts/files/api.ts b/apps/docs/scripts/files/api.ts new file mode 100644 index 00000000000..ed98a9c4921 --- /dev/null +++ b/apps/docs/scripts/files/api.ts @@ -0,0 +1,43 @@ +import crypto from 'crypto' +import { flattenSections } from '../../lib/helpers' + +import apiCommonSections from '~/../../spec/common-api-sections.json' +import specFile from '~/../../spec/transforms/api_v0_openapi_deparsed.json' +import { gen_v3 } from '../../lib/refGenerator/helpers' + +// @ts-ignore +const generatedSpec = gen_v3(specFile, 'wat', { apiUrl: 'apiv0' }) +const sections = flattenSections(apiCommonSections) + +export function generateAPISearchObjects() { + let searchObjects = [] + + //@ts-ignore + sections.map((section) => { + const object = searchObjects.push({ + objectID: crypto.randomUUID(), + id: section.id, + title: section.title, + // @ts-ignore + description: generatedSpec.operations.find((item) => item.operationId === section.id) + ?.summary, + url: `/reference/api/${section.slug}`, + source: 'reference', + pageContent: '', + category: section.product, + version: '', + type: 'lvl2', + hierarchy: { + lvl0: 'References', + lvl1: 'Management API', + lvl2: section.title, + lvl3: null, + lvl4: null, + lvl5: null, + lvl6: null, + }, + }) + return object + }) + return searchObjects +} diff --git a/apps/docs/scripts/files/cli.ts b/apps/docs/scripts/files/cli.ts new file mode 100644 index 00000000000..84caae225c6 --- /dev/null +++ b/apps/docs/scripts/files/cli.ts @@ -0,0 +1,43 @@ +import crypto from 'crypto' +import fs from 'fs' +import { flattenSections } from '../../lib/helpers' +import cliCommonSections from '~/../../spec/common-cli-sections.json' +import yaml from 'js-yaml' + +// @ts-ignore + +const spec = yaml.load(fs.readFileSync(`../../spec/cli_v1_commands.yaml`, 'utf8')) + +const commonSections = flattenSections(cliCommonSections) + +export function generateCLISearchObjects() { + let searchObjects = [] + + //@ts-ignore + spec.commands.map((section) => { + const object = searchObjects.push({ + objectID: crypto.randomUUID(), + id: section.id, + title: section.title, + // @ts-ignore + description: section.description?.substr(0, section.description.indexOf('\n')), + url: `/reference/cli/${commonSections.find((item) => item.id === section.id)?.slug}`, + source: 'reference', + pageContent: '', + category: section.product, + version: '', + type: 'lvl2', + hierarchy: { + lvl0: 'References', + lvl1: 'Supabase CLI', + lvl2: section.title, + lvl3: null, + lvl4: null, + lvl5: null, + lvl6: null, + }, + }) + return object + }) + return searchObjects +} diff --git a/apps/docs/scripts/files/client-libs.ts b/apps/docs/scripts/files/client-libs.ts new file mode 100644 index 00000000000..714769ebcc7 --- /dev/null +++ b/apps/docs/scripts/files/client-libs.ts @@ -0,0 +1,57 @@ +import fs from 'fs' +import crypto from 'crypto' +import yaml from 'js-yaml' +import { flattenSections } from '../../lib/helpers' +import { nameMap } from '../helpers' + +import commonLibSections from '~/../../spec/common-client-libs-sections.json' + +const clientLibFiles = [ + { fileName: 'supabase_js_v2', label: 'javascript', version: 'v2', versionSlug: false }, + { fileName: 'supabase_js_v1', label: 'javascript', version: 'v1', versionSlug: true }, + { fileName: 'supabase_dart_v1', label: 'dart', version: 'v1', versionSlug: false }, + { fileName: 'supabase_dart_v0', label: 'dart', version: 'v0', versionSlug: true }, + { fileName: 'supabase_dart_v0', label: 'dart', version: 'v0', versionSlug: true }, +] + +const flatCommonLibSections = flattenSections(commonLibSections) + +export function generateClientLibSearchObjects() { + // loop through each spec file, find the correspending entry in the common file and grab the title / description / slug + let clientLibSearchObjects = [] + + clientLibFiles.map((file) => { + const specs = yaml.load(fs.readFileSync(`../../spec/${file.fileName}.yml`, 'utf8')) + + //take each function id, find it in the commonLibSections file and return { id, title, slug, description, } + //@ts-ignore + specs.functions.map((fn) => { + const item = flatCommonLibSections.find((section) => section.id === fn.id) + if (item) { + const object = clientLibSearchObjects.push({ + objectID: crypto.randomUUID(), + id: item.id, + title: item.title, + description: item.title, + url: `/reference/${file.label}/${file.versionSlug ? file.version + '/' : ''}${item.slug}`, + source: 'reference', + pageContent: '', + category: item.product, + version: file.version, + type: 'lvl2', + hierarchy: { + lvl0: 'References', + lvl1: `${nameMap[file.label]} ${file.version}`, + lvl2: item.title, + lvl3: file.version, + lvl4: null, + lvl5: null, + lvl6: null, + }, + }) + return object + } + }) + }) + return clientLibSearchObjects +} diff --git a/apps/docs/scripts/helpers.ts b/apps/docs/scripts/helpers.ts new file mode 100644 index 00000000000..97ae8ddb86e --- /dev/null +++ b/apps/docs/scripts/helpers.ts @@ -0,0 +1,9 @@ +export const nameMap = { + api: 'Management API', + cli: 'Supabase CLI', + auth: 'Auth Server', + storage: 'Storage Server', + postgres: 'Postgres', + dart: 'Supabase Flutter Library', + javascript: 'Supabase JavaScript Library', +} diff --git a/apps/docs/scripts/tsconfig.json b/apps/docs/scripts/tsconfig.json new file mode 100644 index 00000000000..de1ecb67a32 --- /dev/null +++ b/apps/docs/scripts/tsconfig.json @@ -0,0 +1,15 @@ +// generator files need their own tsconfig.json because they don't like "module": "esnext" setting that nextjs requires in the main tsconfig +{ + "compilerOptions": { + "incremental": true, + "noImplicitAny": false, + "esModuleInterop": true, + "resolveJsonModule": true, + "baseUrl": ".", + "paths": { + "~/*": ["./*"] + } + }, + "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx"], + "exclude": ["node_modules"] +}