diff --git a/.cspell.json b/.cspell.json index 31c5434cbcd..14d552dfd19 100644 --- a/.cspell.json +++ b/.cspell.json @@ -10,6 +10,7 @@ "adjustednumberoflikes", "allo", "Animalia", + "Argb", "ARROWUP", "Artemia", "Artemiidae", @@ -37,6 +38,7 @@ "coveo", "coveobueno", "coveointernaltesting", + "coveosearch", "coveotaggedword", "coversationid", "CRGA", diff --git a/packages/headless/package.json b/packages/headless/package.json index 5d3f73807e5..e20375a68ab 100644 --- a/packages/headless/package.json +++ b/packages/headless/package.json @@ -40,6 +40,9 @@ "publish:npm": "npm run-script -w=@coveo/release npm-publish", "publish:bump": "npm run-script -w=@coveo/release bump", "promote:npm:latest": "node ../../scripts/deploy/update-npm-tag.mjs latest", + "build:typedoc": "npm run build:typedoc:plugin && npm run build:typedoc:docs", + "build:typedoc:plugin": "npx tsc -p typedoc/tsconfig.json", + "build:typedoc:docs": "typedoc --tsconfig tsconfig.typedoc.json", "build:doc": "npm run build:doc:extract && npm run build:doc:parse", "build:doc:extract": "node ./scripts/extract-documentation.mjs", "build:doc:parse": "ts-node --project ./doc-parser/tsconfig.build.json ./doc-parser/doc-parser.ts" diff --git a/packages/headless/project.json b/packages/headless/project.json index 84a368bee8c..79684655b6f 100644 --- a/packages/headless/project.json +++ b/packages/headless/project.json @@ -18,7 +18,7 @@ ], "executor": "nx:run-commands", "options": { - "commands": ["npm run build:prod", "npm run build:doc"], + "commands": ["npm run build:prod"], "parallel": false, "cwd": "packages/headless" } diff --git a/packages/headless/tsconfig.typedoc.json b/packages/headless/tsconfig.typedoc.json new file mode 100644 index 00000000000..bdaf84e245f --- /dev/null +++ b/packages/headless/tsconfig.typedoc.json @@ -0,0 +1,8 @@ +{ + "extends": "./tsconfig.json", + "compilerOptions": { + "jsx": "react", + "jsxFactory": "JSX.createElement", + "jsxFragmentFactory": "JSX.Fragment" + } +} diff --git a/packages/headless/typedoc.json b/packages/headless/typedoc.json index 9dce36b5633..e1090567f4c 100644 --- a/packages/headless/typedoc.json +++ b/packages/headless/typedoc.json @@ -14,5 +14,6 @@ "./src/ssr.index.ts" ], "projectDocuments": ["./src/docs/usage.md"], - "gitRevision": "typedoc-POC" + "gitRevision": "typedoc-POC", + "plugin": ["./typedoc/dist/index.js"] } diff --git a/packages/headless/typedoc/assets/coveo-docs-logo.svg b/packages/headless/typedoc/assets/coveo-docs-logo.svg new file mode 100644 index 00000000000..bf9faa0bfa4 --- /dev/null +++ b/packages/headless/typedoc/assets/coveo-docs-logo.svg @@ -0,0 +1,66 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + docs + + + + diff --git a/packages/headless/typedoc/assets/docs-style.css b/packages/headless/typedoc/assets/docs-style.css new file mode 100644 index 00000000000..bd413516b04 --- /dev/null +++ b/packages/headless/typedoc/assets/docs-style.css @@ -0,0 +1,82 @@ +:root { + --light-color-background: #fff; + --light-color-background-secondary: #333357; + --light-color-text: #282829; + --light-color-text-aside: #399ffe; + --dark-color-background: #3f3f71; + --dark-color-background-secondary: #333357; + --dark-color-text: #f1f2ff; + --dark-color-text-aside: #399ffe; + --header-height: 5.5rem; +} + +body { + font: + 100 1em/1.625 'canada-type-gibson', + sans-serif; +} + +.tsd-breadcrumb a { + font-weight: 400; +} + +#tsd-search { + width: 27rem; +} + +.tsd-page-toolbar { + height: var(--header-height); + border-bottom: none; +} +.tsd-page-toolbar .tsd-toolbar-contents { + padding: 1.25rem; +} +.tsd-page-toolbar .table-cell:first-child { + width: inherit; + min-width: 11rem; +} +.tsd-page-toolbar .tsd-toolbar-icon { + box-sizing: border-box; + line-height: 0; + padding: 12px 0; +} + +#icon-menu rect { + fill: white; +} + +#tsd-widgets { + padding-left: 0.5rem; + padding-top: 0.25rem; +} +#tsd-widgets .feedback a { + color: white; + font-size: 0.75rem; + font-weight: 400; +} + +@media (max-width: 769px) { + .feedback { + display: none; + } + .has-menu .overlay { + top: var(--header-height); + } + html .col-sidebar { + display: none; + top: var(--header-height) !important; + } + #tsd-search { + display: none; + } + .has-menu #tsd-search { + display: block; + width: 90%; + } + .has-menu .coveo-logo-cell { + display: none; + } + .tsd-widget.active { + background-color: inherit; + } +} diff --git a/packages/headless/typedoc/lib/index.tsx b/packages/headless/typedoc/lib/index.tsx new file mode 100644 index 00000000000..fc7d5f344e6 --- /dev/null +++ b/packages/headless/typedoc/lib/index.tsx @@ -0,0 +1,61 @@ +import {cpSync} from 'node:fs'; +import {dirname, resolve} from 'node:path'; +import {fileURLToPath} from 'node:url'; +// following docs https://typedoc.org/guides/development/#plugins +// eslint-disable-next-line n/no-unpublished-import +import {Application, JSX, RendererEvent} from 'typedoc'; +import {insertAtomicSearchBox} from './insertAtomicSearchBox.js'; +import {insertCoveoLogo} from './insertCoveoLogo.js'; +import {insertSurveyLink} from './insertSurveyLink.js'; + +const __dirname = dirname(fileURLToPath(import.meta.url)); + +/** + * Called by TypeDoc when loaded as a plugin. + */ +export function load(app: Application) { + app.renderer.hooks.on('head.end', (event) => ( + <> + + + + + + + + )); + + const onRenderEnd = () => { + const filesToCopy = [ + { + from: resolve(__dirname, '../assets/docs-style.css'), + to: resolve(app.options.getValue('out'), 'assets/docs-style.css'), + }, + { + from: resolve(__dirname, '../assets/coveo-docs-logo.svg'), + to: resolve(app.options.getValue('out'), 'assets/coveo-docs-logo.svg'), + }, + ]; + + filesToCopy.forEach((file) => { + cpSync(file.from, file.to); + }); + }; + + app.renderer.on(RendererEvent.END, onRenderEnd); +} diff --git a/packages/headless/typedoc/lib/insertAtomicSearchBox.ts b/packages/headless/typedoc/lib/insertAtomicSearchBox.ts new file mode 100644 index 00000000000..480694586cb --- /dev/null +++ b/packages/headless/typedoc/lib/insertAtomicSearchBox.ts @@ -0,0 +1,61 @@ +interface AtomicSearchInterfaceElement extends HTMLElement { + initialize(config: { + organizationId: string; + organizationEndpoints: OrganizationEndpoints; + accessToken: string; + search: {searchHub: string}; + analytics: {originLevel2: string}; + }): Promise; + getOrganizationEndpoints( + organizationId: string + ): Promise; +} + +interface OrganizationEndpoints { + platform: string; + analytics: string; + search: string; + admin: string; +} + +declare global { + interface HTMLElementTagNameMap { + 'atomic-search-interface': AtomicSearchInterfaceElement; + } +} + +export function insertAtomicSearchBox() { + document.addEventListener('DOMContentLoaded', () => { + const typedocSearchBox = document.getElementById('tsd-search'); + if (typedocSearchBox) { + typedocSearchBox.innerHTML = ''; + const searchInterface = document.createElement('atomic-search-interface'); + const searchBox = document.createElement('atomic-search-box'); + searchBox.setAttribute( + 'redirection-url', + 'https://docs.coveo.com/en/search' + ); + searchInterface.appendChild(searchBox); + typedocSearchBox.appendChild(searchInterface); + + (async () => { + await customElements.whenDefined('atomic-search-interface'); + const searchInterfaceElement = document.querySelector( + 'atomic-search-interface' + ); + if (searchInterfaceElement) { + await searchInterfaceElement.initialize({ + organizationId: 'coveosearch', + organizationEndpoints: + await searchInterfaceElement.getOrganizationEndpoints( + 'coveosearch' + ), + accessToken: 'xx6ac9d08f-eb9a-48d5-9240-d7c251470c93', + search: {searchHub: 'Coveo Docs Unified Search'}, + analytics: {originLevel2: 'All'}, + }); + } + })(); + } + }); +} diff --git a/packages/headless/typedoc/lib/insertCoveoLogo.ts b/packages/headless/typedoc/lib/insertCoveoLogo.ts new file mode 100644 index 00000000000..b5e0800c70e --- /dev/null +++ b/packages/headless/typedoc/lib/insertCoveoLogo.ts @@ -0,0 +1,23 @@ +export function insertCoveoLogo() { + document.addEventListener('DOMContentLoaded', () => { + const toolbarContents = document.getElementsByClassName( + 'tsd-toolbar-contents' + )[0]; + if (toolbarContents) { + const logoCell = document.createElement('div'); + logoCell.classList.add('table-cell', 'coveo-logo-cell'); + const logoDiv = document.createElement('div'); + logoDiv.classList.add('coveo-logo'); + const logoLink = document.createElement('a'); + logoLink.href = 'https://docs.coveo.com/en/0'; + const logoImg = document.createElement('img'); + logoImg.src = './assets/coveo-docs-logo.svg'; + logoImg.alt = 'Coveo Docs Logo'; + + logoLink.appendChild(logoImg); + logoDiv.appendChild(logoLink); + logoCell.appendChild(logoDiv); + toolbarContents.insertBefore(logoCell, toolbarContents.firstChild); + } + }); +} diff --git a/packages/headless/typedoc/lib/insertSurveyLink.ts b/packages/headless/typedoc/lib/insertSurveyLink.ts new file mode 100644 index 00000000000..152146a1019 --- /dev/null +++ b/packages/headless/typedoc/lib/insertSurveyLink.ts @@ -0,0 +1,16 @@ +export function insertSurveyLink() { + document.addEventListener('DOMContentLoaded', () => { + const toolbarWidgets = document.getElementById('tsd-widgets'); + if (toolbarWidgets) { + const feedbackDiv = document.createElement('div'); + feedbackDiv.classList.add('feedback'); + const feedbackLink = document.createElement('a'); + feedbackLink.href = + 'https://docs.google.com/forms/d/e/1FAIpQLSeyNL18g4JWIDR5xEyIMY48JIjyjwXRmlCveecjXBNSLh4Ygg/viewform'; + feedbackLink.target = '_blank'; + feedbackLink.textContent = 'Feedback'; + feedbackDiv.appendChild(feedbackLink); + toolbarWidgets.appendChild(feedbackDiv); + } + }); +} diff --git a/packages/headless/typedoc/package-lock.json b/packages/headless/typedoc/package-lock.json new file mode 100644 index 00000000000..98a0b8ae4d6 --- /dev/null +++ b/packages/headless/typedoc/package-lock.json @@ -0,0 +1,213 @@ +{ + "name": "typedoc", + "lockfileVersion": 3, + "requires": true, + "packages": { + "": { + "devDependencies": { + "typedoc": "0.26.4" + } + }, + "node_modules/@shikijs/core": { + "version": "1.14.1", + "resolved": "https://registry.npmjs.org/@shikijs/core/-/core-1.14.1.tgz", + "integrity": "sha512-KyHIIpKNaT20FtFPFjCQB5WVSTpLR/n+jQXhWHWVUMm9MaOaG9BGOG0MSyt7yA4+Lm+4c9rTc03tt3nYzeYSfw==", + "dev": true, + "license": "MIT", + "dependencies": { + "@types/hast": "^3.0.4" + } + }, + "node_modules/@types/hast": { + "version": "3.0.4", + "resolved": "https://registry.npmjs.org/@types/hast/-/hast-3.0.4.tgz", + "integrity": "sha512-WPs+bbQw5aCj+x6laNGWLH3wviHtoCv/P3+otBhbOhJgG8qtpdAMlTCxLtsTWA7LH1Oh/bFCHsBn0TPS5m30EQ==", + "dev": true, + "license": "MIT", + "dependencies": { + "@types/unist": "*" + } + }, + "node_modules/@types/unist": { + "version": "3.0.3", + "resolved": "https://registry.npmjs.org/@types/unist/-/unist-3.0.3.tgz", + "integrity": "sha512-ko/gIFJRv177XgZsZcBwnqJN5x/Gien8qNOn0D5bQU/zAzVf9Zt3BlcUiLqhV9y4ARk0GbT3tnUiPNgnTXzc/Q==", + "dev": true, + "license": "MIT" + }, + "node_modules/argparse": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/argparse/-/argparse-2.0.1.tgz", + "integrity": "sha512-8+9WqebbFzpX9OR+Wa6O29asIogeRMzcGtAINdpMHHyAg10f05aSFVBbcEqGf/PXw1EjAZ+q2/bEBg3DvurK3Q==", + "dev": true, + "license": "Python-2.0" + }, + "node_modules/balanced-match": { + "version": "1.0.2", + "resolved": "https://registry.npmjs.org/balanced-match/-/balanced-match-1.0.2.tgz", + "integrity": "sha512-3oSeUO0TMV67hN1AmbXsK4yaqU7tjiHlbxRDZOpH0KW9+CeX4bRAaX0Anxt0tx2MrpRpWwQaPwIlISEJhYU5Pw==", + "dev": true, + "license": "MIT" + }, + "node_modules/brace-expansion": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-2.0.1.tgz", + "integrity": "sha512-XnAIvQ8eM+kC6aULx6wuQiwVsnzsi9d3WxzV3FpWTGA19F621kwdbsAcFKXgKUHZWsy+mY6iL1sHTxWEFCytDA==", + "dev": true, + "license": "MIT", + "dependencies": { + "balanced-match": "^1.0.0" + } + }, + "node_modules/entities": { + "version": "4.5.0", + "resolved": "https://registry.npmjs.org/entities/-/entities-4.5.0.tgz", + "integrity": "sha512-V0hjH4dGPh9Ao5p0MoRY6BVqtwCjhz6vI5LT8AJ55H+4g9/4vbHx1I54fS0XuclLhDHArPQCiMjDxjaL8fPxhw==", + "dev": true, + "license": "BSD-2-Clause", + "engines": { + "node": ">=0.12" + }, + "funding": { + "url": "https://github.com/fb55/entities?sponsor=1" + } + }, + "node_modules/linkify-it": { + "version": "5.0.0", + "resolved": "https://registry.npmjs.org/linkify-it/-/linkify-it-5.0.0.tgz", + "integrity": "sha512-5aHCbzQRADcdP+ATqnDuhhJ/MRIqDkZX5pyjFHRRysS8vZ5AbqGEoFIb6pYHPZ+L/OC2Lc+xT8uHVVR5CAK/wQ==", + "dev": true, + "license": "MIT", + "dependencies": { + "uc.micro": "^2.0.0" + } + }, + "node_modules/lunr": { + "version": "2.3.9", + "resolved": "https://registry.npmjs.org/lunr/-/lunr-2.3.9.tgz", + "integrity": "sha512-zTU3DaZaF3Rt9rhN3uBMGQD3dD2/vFQqnvZCDv4dl5iOzq2IZQqTxu90r4E5J+nP70J3ilqVCrbho2eWaeW8Ow==", + "dev": true, + "license": "MIT" + }, + "node_modules/markdown-it": { + "version": "14.1.0", + "resolved": "https://registry.npmjs.org/markdown-it/-/markdown-it-14.1.0.tgz", + "integrity": "sha512-a54IwgWPaeBCAAsv13YgmALOF1elABB08FxO9i+r4VFk5Vl4pKokRPeX8u5TCgSsPi6ec1otfLjdOpVcgbpshg==", + "dev": true, + "license": "MIT", + "dependencies": { + "argparse": "^2.0.1", + "entities": "^4.4.0", + "linkify-it": "^5.0.0", + "mdurl": "^2.0.0", + "punycode.js": "^2.3.1", + "uc.micro": "^2.1.0" + }, + "bin": { + "markdown-it": "bin/markdown-it.mjs" + } + }, + "node_modules/mdurl": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/mdurl/-/mdurl-2.0.0.tgz", + "integrity": "sha512-Lf+9+2r+Tdp5wXDXC4PcIBjTDtq4UKjCPMQhKIuzpJNW0b96kVqSwW0bT7FhRSfmAiFYgP+SCRvdrDozfh0U5w==", + "dev": true, + "license": "MIT" + }, + "node_modules/minimatch": { + "version": "9.0.5", + "resolved": "https://registry.npmjs.org/minimatch/-/minimatch-9.0.5.tgz", + "integrity": "sha512-G6T0ZX48xgozx7587koeX9Ys2NYy6Gmv//P89sEte9V9whIapMNF4idKxnW2QtCcLiTWlb/wfCabAtAFWhhBow==", + "dev": true, + "license": "ISC", + "dependencies": { + "brace-expansion": "^2.0.1" + }, + "engines": { + "node": ">=16 || 14 >=14.17" + }, + "funding": { + "url": "https://github.com/sponsors/isaacs" + } + }, + "node_modules/punycode.js": { + "version": "2.3.1", + "resolved": "https://registry.npmjs.org/punycode.js/-/punycode.js-2.3.1.tgz", + "integrity": "sha512-uxFIHU0YlHYhDQtV4R9J6a52SLx28BCjT+4ieh7IGbgwVJWO+km431c4yRlREUAsAmt/uMjQUyQHNEPf0M39CA==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=6" + } + }, + "node_modules/shiki": { + "version": "1.14.1", + "resolved": "https://registry.npmjs.org/shiki/-/shiki-1.14.1.tgz", + "integrity": "sha512-FujAN40NEejeXdzPt+3sZ3F2dx1U24BY2XTY01+MG8mbxCiA2XukXdcbyMyLAHJ/1AUUnQd1tZlvIjefWWEJeA==", + "dev": true, + "license": "MIT", + "dependencies": { + "@shikijs/core": "1.14.1", + "@types/hast": "^3.0.4" + } + }, + "node_modules/typedoc": { + "version": "0.26.4", + "resolved": "https://registry.npmjs.org/typedoc/-/typedoc-0.26.4.tgz", + "integrity": "sha512-FlW6HpvULDKgc3rK04V+nbFyXogPV88hurarDPOjuuB5HAwuAlrCMQ5NeH7Zt68a/ikOKu6Z/0hFXAeC9xPccQ==", + "dev": true, + "license": "Apache-2.0", + "dependencies": { + "lunr": "^2.3.9", + "markdown-it": "^14.1.0", + "minimatch": "^9.0.5", + "shiki": "^1.9.1", + "yaml": "^2.4.5" + }, + "bin": { + "typedoc": "bin/typedoc" + }, + "engines": { + "node": ">= 18" + }, + "peerDependencies": { + "typescript": "4.6.x || 4.7.x || 4.8.x || 4.9.x || 5.0.x || 5.1.x || 5.2.x || 5.3.x || 5.4.x || 5.5.x" + } + }, + "node_modules/typescript": { + "version": "5.5.4", + "resolved": "https://registry.npmjs.org/typescript/-/typescript-5.5.4.tgz", + "integrity": "sha512-Mtq29sKDAEYP7aljRgtPOpTvOfbwRWlS6dPRzwjdE+C0R4brX/GUyhHSecbHMFLNBLcJIPt9nl9yG5TZ1weH+Q==", + "dev": true, + "license": "Apache-2.0", + "peer": true, + "bin": { + "tsc": "bin/tsc", + "tsserver": "bin/tsserver" + }, + "engines": { + "node": ">=14.17" + } + }, + "node_modules/uc.micro": { + "version": "2.1.0", + "resolved": "https://registry.npmjs.org/uc.micro/-/uc.micro-2.1.0.tgz", + "integrity": "sha512-ARDJmphmdvUk6Glw7y9DQ2bFkKBHwQHLi2lsaH6PPmz/Ka9sFOBsBluozhDltWmnv9u/cF6Rt87znRTPV+yp/A==", + "dev": true, + "license": "MIT" + }, + "node_modules/yaml": { + "version": "2.5.0", + "resolved": "https://registry.npmjs.org/yaml/-/yaml-2.5.0.tgz", + "integrity": "sha512-2wWLbGbYDiSqqIKoPjar3MPgB94ErzCtrNE1FdqGuaO0pi2JGjmE8aW8TDZwzU7vuxcGRdL/4gPQwQ7hD5AMSw==", + "dev": true, + "license": "ISC", + "bin": { + "yaml": "bin.mjs" + }, + "engines": { + "node": ">= 14" + } + } + } +} diff --git a/packages/headless/typedoc/package.json b/packages/headless/typedoc/package.json new file mode 100644 index 00000000000..4fa67e72803 --- /dev/null +++ b/packages/headless/typedoc/package.json @@ -0,0 +1,6 @@ +{ + "type": "module", + "devDependencies": { + "typedoc": "0.26.4" + } +} diff --git a/packages/headless/typedoc/tsconfig.json b/packages/headless/typedoc/tsconfig.json new file mode 100644 index 00000000000..6788f5298ef --- /dev/null +++ b/packages/headless/typedoc/tsconfig.json @@ -0,0 +1,8 @@ +{ + "extends": "../tsconfig.typedoc.json", + "compilerOptions": { + "outDir": "dist", + "rootDir": "lib" + }, + "include": ["lib/**/*"] +}