diff --git a/package-lock.json b/package-lock.json index 7ad2165649..83a6d458be 100644 --- a/package-lock.json +++ b/package-lock.json @@ -12,6 +12,9 @@ "workspaces": [ "packages/*" ], + "dependencies": { + "clipboardy": "^4.0.0" + }, "devDependencies": { "@babel/cli": "^7.26.4", "@commitlint/cli": "^19.6.0", @@ -4188,9 +4191,9 @@ } }, "node_modules/@jsdoc/salty": { - "version": "0.2.8", - "resolved": "https://registry.npmjs.org/@jsdoc/salty/-/salty-0.2.8.tgz", - "integrity": "sha512-5e+SFVavj1ORKlKaKr2BmTOekmXbelU7dC0cDkQLqag7xfuTPuGMUFx7KWJuv4bYZrTsoL2Z18VVCOKYxzoHcg==", + "version": "0.2.9", + "resolved": "https://registry.npmjs.org/@jsdoc/salty/-/salty-0.2.9.tgz", + "integrity": "sha512-yYxMVH7Dqw6nO0d5NIV8OQWnitU8k6vXH8NtgqAfIa/IUqRMxRv/NUJJ08VEKbAakwxlgBl5PJdrU0dMPStsnw==", "dev": true, "license": "Apache-2.0", "dependencies": { @@ -12424,24 +12427,24 @@ "license": "ISC" }, "node_modules/cache-point": { - "version": "2.0.0", + "version": "3.0.1", + "resolved": "https://registry.npmjs.org/cache-point/-/cache-point-3.0.1.tgz", + "integrity": "sha512-itTIMLEKbh6Dw5DruXbxAgcyLnh/oPGVLBfTPqBOftASxHe8bAeXy7JkO4F0LvHqht7XqP5O/09h5UcHS2w0FA==", "dev": true, "license": "MIT", "dependencies": { - "array-back": "^4.0.1", - "fs-then-native": "^2.0.0", - "mkdirp2": "^1.0.4" + "array-back": "^6.2.2" }, "engines": { - "node": ">=8" - } - }, - "node_modules/cache-point/node_modules/array-back": { - "version": "4.0.2", - "dev": true, - "license": "MIT", - "engines": { - "node": ">=8" + "node": ">=12.17" + }, + "peerDependencies": { + "@75lb/nature": "latest" + }, + "peerDependenciesMeta": { + "@75lb/nature": { + "optional": true + } } }, "node_modules/cachedir": { @@ -13002,6 +13005,172 @@ "url": "https://github.com/chalk/strip-ansi?sponsor=1" } }, + "node_modules/clipboardy": { + "version": "4.0.0", + "resolved": "https://registry.npmjs.org/clipboardy/-/clipboardy-4.0.0.tgz", + "integrity": "sha512-5mOlNS0mhX0707P2I0aZ2V/cmHUEO/fL7VFLqszkhUsxt7RwnmrInf/eEQKlf5GzvYeHIjT+Ov1HRfNmymlG0w==", + "license": "MIT", + "dependencies": { + "execa": "^8.0.1", + "is-wsl": "^3.1.0", + "is64bit": "^2.0.0" + }, + "engines": { + "node": ">=18" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, + "node_modules/clipboardy/node_modules/execa": { + "version": "8.0.1", + "resolved": "https://registry.npmjs.org/execa/-/execa-8.0.1.tgz", + "integrity": "sha512-VyhnebXciFV2DESc+p6B+y0LjSm0krU4OgJN44qFAhBY0TJ+1V61tYD2+wHusZ6F9n5K+vl8k0sTy7PEfV4qpg==", + "license": "MIT", + "dependencies": { + "cross-spawn": "^7.0.3", + "get-stream": "^8.0.1", + "human-signals": "^5.0.0", + "is-stream": "^3.0.0", + "merge-stream": "^2.0.0", + "npm-run-path": "^5.1.0", + "onetime": "^6.0.0", + "signal-exit": "^4.1.0", + "strip-final-newline": "^3.0.0" + }, + "engines": { + "node": ">=16.17" + }, + "funding": { + "url": "https://github.com/sindresorhus/execa?sponsor=1" + } + }, + "node_modules/clipboardy/node_modules/get-stream": { + "version": "8.0.1", + "resolved": "https://registry.npmjs.org/get-stream/-/get-stream-8.0.1.tgz", + "integrity": "sha512-VaUJspBffn/LMCJVoMvSAdmscJyS1auj5Zulnn5UoYcY531UWmdwhRWkcGKnGU93m5HSXP9LP2usOryrBtQowA==", + "license": "MIT", + "engines": { + "node": ">=16" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, + "node_modules/clipboardy/node_modules/human-signals": { + "version": "5.0.0", + "resolved": "https://registry.npmjs.org/human-signals/-/human-signals-5.0.0.tgz", + "integrity": "sha512-AXcZb6vzzrFAUE61HnN4mpLqd/cSIwNQjtNWR0euPm6y0iqx3G4gOXaIDdtdDwZmhwe82LA6+zinmW4UBWVePQ==", + "license": "Apache-2.0", + "engines": { + "node": ">=16.17.0" + } + }, + "node_modules/clipboardy/node_modules/is-stream": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/is-stream/-/is-stream-3.0.0.tgz", + "integrity": "sha512-LnQR4bZ9IADDRSkvpqMGvt/tEJWclzklNgSw48V5EAaAeDd6qGvN8ei6k5p0tvxSR171VmGyHuTiAOfxAbr8kA==", + "license": "MIT", + "engines": { + "node": "^12.20.0 || ^14.13.1 || >=16.0.0" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, + "node_modules/clipboardy/node_modules/is-wsl": { + "version": "3.1.0", + "resolved": "https://registry.npmjs.org/is-wsl/-/is-wsl-3.1.0.tgz", + "integrity": "sha512-UcVfVfaK4Sc4m7X3dUSoHoozQGBEFeDC+zVo06t98xe8CzHSZZBekNXH+tu0NalHolcJ/QAGqS46Hef7QXBIMw==", + "license": "MIT", + "dependencies": { + "is-inside-container": "^1.0.0" + }, + "engines": { + "node": ">=16" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, + "node_modules/clipboardy/node_modules/mimic-fn": { + "version": "4.0.0", + "resolved": "https://registry.npmjs.org/mimic-fn/-/mimic-fn-4.0.0.tgz", + "integrity": "sha512-vqiC06CuhBTUdZH+RYl8sFrL096vA45Ok5ISO6sE/Mr1jRbGH4Csnhi8f3wKVl7x8mO4Au7Ir9D3Oyv1VYMFJw==", + "license": "MIT", + "engines": { + "node": ">=12" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, + "node_modules/clipboardy/node_modules/npm-run-path": { + "version": "5.3.0", + "resolved": "https://registry.npmjs.org/npm-run-path/-/npm-run-path-5.3.0.tgz", + "integrity": "sha512-ppwTtiJZq0O/ai0z7yfudtBpWIoxM8yE6nHi1X47eFR2EWORqfbu6CnPlNsjeN683eT0qG6H/Pyf9fCcvjnnnQ==", + "license": "MIT", + "dependencies": { + "path-key": "^4.0.0" + }, + "engines": { + "node": "^12.20.0 || ^14.13.1 || >=16.0.0" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, + "node_modules/clipboardy/node_modules/onetime": { + "version": "6.0.0", + "resolved": "https://registry.npmjs.org/onetime/-/onetime-6.0.0.tgz", + "integrity": "sha512-1FlR+gjXK7X+AsAHso35MnyN5KqGwJRi/31ft6x0M194ht7S+rWAvd7PHss9xSKMzE0asv1pyIHaJYq+BbacAQ==", + "license": "MIT", + "dependencies": { + "mimic-fn": "^4.0.0" + }, + "engines": { + "node": ">=12" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, + "node_modules/clipboardy/node_modules/path-key": { + "version": "4.0.0", + "resolved": "https://registry.npmjs.org/path-key/-/path-key-4.0.0.tgz", + "integrity": "sha512-haREypq7xkM7ErfgIyA0z+Bj4AGKlMSdlQE2jvJo6huWD1EdkKYV+G/T4nq0YEF2vgTT8kqMFKo1uHn950r4SQ==", + "license": "MIT", + "engines": { + "node": ">=12" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, + "node_modules/clipboardy/node_modules/signal-exit": { + "version": "4.1.0", + "resolved": "https://registry.npmjs.org/signal-exit/-/signal-exit-4.1.0.tgz", + "integrity": "sha512-bzyZ1e88w9O1iNJbKnOlvYTrWPDl46O1bG0D3XInv+9tkPrxrN8jUUTiFlDkkmKWgn1M6CfIA13SuGqOa9Korw==", + "license": "ISC", + "engines": { + "node": ">=14" + }, + "funding": { + "url": "https://github.com/sponsors/isaacs" + } + }, + "node_modules/clipboardy/node_modules/strip-final-newline": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/strip-final-newline/-/strip-final-newline-3.0.0.tgz", + "integrity": "sha512-dOESqjYr96iWYylGObzd39EuNTa5VJxyvVAEm5Jnh7KGo75V43Hk1odPQkNDyXNmUR6k+gEiDVXnjB8HJ3crXw==", + "license": "MIT", + "engines": { + "node": ">=12" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, "node_modules/cliui": { "version": "7.0.4", "license": "ISC", @@ -13309,18 +13478,6 @@ "node": ">= 4.0.0" } }, - "node_modules/collect-all": { - "version": "1.0.4", - "dev": true, - "license": "MIT", - "dependencies": { - "stream-connect": "^1.0.2", - "stream-via": "^1.0.4" - }, - "engines": { - "node": ">=0.10.0" - } - }, "node_modules/color-convert": { "version": "2.0.1", "license": "MIT", @@ -14487,6 +14644,16 @@ "dev": true, "license": "MIT" }, + "node_modules/current-module-paths": { + "version": "1.1.2", + "resolved": "https://registry.npmjs.org/current-module-paths/-/current-module-paths-1.1.2.tgz", + "integrity": "sha512-H4s4arcLx/ugbu1XkkgSvcUZax0L6tXUqnppGniQb8l5VjUKGHoayXE5RiriiPhYDd+kjZnaok1Uig13PKtKYQ==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=12.17" + } + }, "node_modules/custom-event": { "version": "1.0.1", "license": "MIT" @@ -17503,23 +17670,25 @@ } }, "node_modules/file-set": { - "version": "4.0.2", + "version": "5.2.2", + "resolved": "https://registry.npmjs.org/file-set/-/file-set-5.2.2.tgz", + "integrity": "sha512-/KgJI1V/QaDK4enOk/E2xMFk1cTWJghEr7UmWiRZfZ6upt6gQCfMn4jJ7aOm64OKurj4TaVnSSgSDqv5ZKYA3A==", "dev": true, "license": "MIT", "dependencies": { - "array-back": "^5.0.0", - "glob": "^7.1.6" + "array-back": "^6.2.2", + "fast-glob": "^3.3.2" }, "engines": { - "node": ">=10" - } - }, - "node_modules/file-set/node_modules/array-back": { - "version": "5.0.0", - "dev": true, - "license": "MIT", - "engines": { - "node": ">=10" + "node": ">=12.17" + }, + "peerDependencies": { + "@75lb/nature": "latest" + }, + "peerDependenciesMeta": { + "@75lb/nature": { + "optional": true + } } }, "node_modules/file-system-cache": { @@ -18165,14 +18334,6 @@ "version": "1.1.0", "license": "MIT" }, - "node_modules/fs-then-native": { - "version": "2.0.0", - "dev": true, - "license": "MIT", - "engines": { - "node": ">=4.0.0" - } - }, "node_modules/fs-write-stream-atomic": { "version": "1.0.10", "license": "ISC", @@ -20577,6 +20738,21 @@ "node": ">=8" } }, + "node_modules/is64bit": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/is64bit/-/is64bit-2.0.0.tgz", + "integrity": "sha512-jv+8jaWCl0g2lSBkNSVXdzfBA0npK1HGC2KtWM9FumFRoGS94g3NbCCLVnCYHLjp4GrW2KZeeSTMo5ddtznmGw==", + "license": "MIT", + "dependencies": { + "system-architecture": "^0.1.0" + }, + "engines": { + "node": ">=18" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, "node_modules/isarray": { "version": "2.0.5", "license": "MIT" @@ -21034,9 +21210,9 @@ } }, "node_modules/jsdoc": { - "version": "4.0.3", - "resolved": "https://registry.npmjs.org/jsdoc/-/jsdoc-4.0.3.tgz", - "integrity": "sha512-Nu7Sf35kXJ1MWDZIMAuATRQTg1iIPdzh7tqJ6jjvaU/GfDf+qi5UV8zJR3Mo+/pYFvm8mzay4+6O5EWigaQBQw==", + "version": "4.0.4", + "resolved": "https://registry.npmjs.org/jsdoc/-/jsdoc-4.0.4.tgz", + "integrity": "sha512-zeFezwyXeG4syyYHbvh1A967IAqq/67yXtXvuL5wnqCkFZe8I0vKfm+EO+YEvLguo6w9CDUbrAXVtJSHh2E8rw==", "dev": true, "license": "Apache-2.0", "dependencies": { @@ -21064,24 +21240,30 @@ } }, "node_modules/jsdoc-api": { - "version": "8.1.1", - "resolved": "https://registry.npmjs.org/jsdoc-api/-/jsdoc-api-8.1.1.tgz", - "integrity": "sha512-yas9E4h8NHp1CTEZiU/DPNAvLoUcip+Hl8Xi1RBYzHqSrgsF+mImAZNtwymrXvgbrgl4bNGBU9syulM0JzFeHQ==", + "version": "9.3.4", + "resolved": "https://registry.npmjs.org/jsdoc-api/-/jsdoc-api-9.3.4.tgz", + "integrity": "sha512-di8lggLACEttpyAZ6WjKKafUP4wC4prAGjt40nMl7quDpp2nD7GmLt6/WxhRu9Q6IYoAAySsNeidBXYVAMwlqg==", "dev": true, "license": "MIT", "dependencies": { "array-back": "^6.2.2", - "cache-point": "^2.0.0", - "collect-all": "^1.0.4", - "file-set": "^4.0.2", - "fs-then-native": "^2.0.0", - "jsdoc": "^4.0.3", + "cache-point": "^3.0.0", + "current-module-paths": "^1.1.2", + "file-set": "^5.2.2", + "jsdoc": "^4.0.4", "object-to-spawn-args": "^2.0.1", - "temp-path": "^1.0.0", - "walk-back": "^5.1.0" + "walk-back": "^5.1.1" }, "engines": { "node": ">=12.17" + }, + "peerDependencies": { + "@75lb/nature": "latest" + }, + "peerDependenciesMeta": { + "@75lb/nature": { + "optional": true + } } }, "node_modules/jsdoc/node_modules/escape-string-regexp": { @@ -24119,11 +24301,6 @@ "integrity": "sha512-gKLcREMhtuZRwRAfqP3RFW+TK4JqApVBtOIftVgjuABpAtpxhPGaDcfvbhNvD0B8iD1oUr/txX35NjcaY6Ns/A==", "dev": true }, - "node_modules/mkdirp2": { - "version": "1.0.5", - "dev": true, - "license": "MIT" - }, "node_modules/mocha": { "version": "10.7.3", "resolved": "https://registry.npmjs.org/mocha/-/mocha-10.7.3.tgz", @@ -29407,28 +29584,6 @@ "component-emitter": "^2.0.0" } }, - "node_modules/stream-connect": { - "version": "1.0.2", - "dev": true, - "license": "MIT", - "dependencies": { - "array-back": "^1.0.2" - }, - "engines": { - "node": ">=0.10.0" - } - }, - "node_modules/stream-connect/node_modules/array-back": { - "version": "1.0.4", - "dev": true, - "license": "MIT", - "dependencies": { - "typical": "^2.6.0" - }, - "engines": { - "node": ">=0.12.0" - } - }, "node_modules/stream-each": { "version": "1.2.3", "license": "MIT", @@ -29441,14 +29596,6 @@ "version": "1.0.1", "license": "MIT" }, - "node_modules/stream-via": { - "version": "1.0.4", - "dev": true, - "license": "MIT", - "engines": { - "node": ">=0.10.0" - } - }, "node_modules/stream/node_modules/component-emitter": { "version": "2.0.0", "resolved": "https://registry.npmjs.org/component-emitter/-/component-emitter-2.0.0.tgz", @@ -30144,6 +30291,18 @@ "version": "2.0.17", "license": "BSD-3-Clause" }, + "node_modules/system-architecture": { + "version": "0.1.0", + "resolved": "https://registry.npmjs.org/system-architecture/-/system-architecture-0.1.0.tgz", + "integrity": "sha512-ulAk51I9UVUyJgxlv9M6lFot2WP3e7t8Kz9+IS6D4rVba1tR9kON+Ey69f+1R4Q8cd45Lod6a4IcJIxnzGc/zA==", + "license": "MIT", + "engines": { + "node": ">=18" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, "node_modules/tapable": { "version": "2.2.1", "resolved": "https://registry.npmjs.org/tapable/-/tapable-2.2.1.tgz", @@ -30398,11 +30557,6 @@ "node": ">=4" } }, - "node_modules/temp-path": { - "version": "1.0.0", - "dev": true, - "license": "MIT" - }, "node_modules/temp/node_modules/mkdirp": { "version": "0.5.6", "license": "MIT", @@ -31582,11 +31736,6 @@ "typescript": ">=4.8.4 <5.8.0" } }, - "node_modules/typical": { - "version": "2.6.1", - "dev": true, - "license": "MIT" - }, "node_modules/ua-parser-js": { "version": "0.7.36", "funding": [ @@ -32830,7 +32979,9 @@ "license": "MIT" }, "node_modules/walk-back": { - "version": "5.1.0", + "version": "5.1.1", + "resolved": "https://registry.npmjs.org/walk-back/-/walk-back-5.1.1.tgz", + "integrity": "sha512-e/FRLDVdZQWFrAzU6Hdvpm7D7m2ina833gIKLptQykRK49mmCYHLHq7UqjPDbxbKLZkTkW1rFqbengdE3sLfdw==", "dev": true, "license": "MIT", "engines": { @@ -34037,7 +34188,7 @@ "globby": "^14.0.2", "gray-matter": "^4.0.3", "html-webpack-plugin": "^5.6.3", - "jsdoc-api": "^8.1.1", + "jsdoc-api": "^9.3.4", "mkdirp": "^3.0.1", "raw-loader": "^4.0.2", "react-docgen": "^7.1.1", diff --git a/package.json b/package.json index 24137ff465..edc117349f 100644 --- a/package.json +++ b/package.json @@ -127,5 +127,8 @@ }, "browserslist": [ "extends @instructure/browserslist-config-instui" - ] + ], + "dependencies": { + "clipboardy": "^4.0.0" + } } diff --git a/packages/__docs__/buildScripts/build-docs.mts b/packages/__docs__/buildScripts/build-docs.mts index 66f0c0efd4..eb2ef1e581 100644 --- a/packages/__docs__/buildScripts/build-docs.mts +++ b/packages/__docs__/buildScripts/build-docs.mts @@ -67,7 +67,7 @@ const pathsToProcess = [ '**/src/*/*.{js,ts,tsx}', // component src files '**/src/*/*/*.{js,ts,tsx}', // child component src files 'CODE_OF_CONDUCT.md', - 'LICENSE.md' + 'LICENSE.md', ] const pathsToIgnore = [ @@ -117,7 +117,7 @@ if (import.meta.url === pathToFileURL(process.argv[1]).href) { buildDocs() } -function buildDocs() { +async function buildDocs() { // eslint-disable-next-line no-console console.log('Start building application data') @@ -127,17 +127,20 @@ function buildDocs() { // globby needs the posix format const files = pathsToProcess.map((file) => path.posix.join(packagesDir, file)) const ignore = pathsToIgnore.map((file) => path.posix.join(packagesDir, file)) + globby(files, { ignore }) - .then((matches) => { + .then(async (matches) => { + fs.mkdirSync(buildDir + 'docs/', { recursive: true }) // eslint-disable-next-line no-console console.log( 'Parsing markdown and source files... (' + matches.length + ' files)' ) - const docs = matches.map((relativePath) => { + const docs = await Promise.all(matches.map(async (relativePath) => { // loop trough every source and Readme file - return processSingleFile(path.resolve(relativePath)) - }) + return await processSingleFile(path.resolve(relativePath)) + })) + const themes = parseThemes() const clientProps = getClientProps(docs, library) const props: MainDocsData = { @@ -146,6 +149,7 @@ function buildDocs() { library } const markdownsAndSources = JSON.stringify(props) + fs.writeFileSync( buildDir + 'markdown-and-sources-data.json', markdownsAndSources @@ -182,12 +186,13 @@ function buildDocs() { // This function is also called by Webpack if a file changes // TODO this parses some files twice, its needed for the Webpack watcher but not // for the full build. -function processSingleFile(fullPath: string) { +async function processSingleFile(fullPath: string) { + let docObject const dirName = path.dirname(fullPath) const fileName = path.parse(fullPath).name if (fileName === 'index') { - docObject = processFile(fullPath, projectRoot, library) + docObject = await processFile(fullPath, projectRoot, library) // Some Components (e.g. Alert) store their descriptions in README.md files. // Add this to the final JSON if it's edited const readmeDesc = tryParseReadme(dirName) @@ -203,20 +208,23 @@ function processSingleFile(fullPath: string) { componentIndexFile = path.join(dirName, 'index.ts') } if (componentIndexFile) { - docObject = processFile(componentIndexFile, projectRoot, library) + docObject = await processFile(componentIndexFile, projectRoot, library) const readmeDesc = tryParseReadme(dirName) docObject.description = readmeDesc ? readmeDesc : docObject.description } else { // just a README.md, has no index file - docObject = processFile(fullPath, projectRoot, library) + docObject = await processFile(fullPath, projectRoot, library) } } else { // documentation .md files, utils ts and tsx files - docObject = processFile(fullPath, projectRoot, library) + docObject = await processFile(fullPath, projectRoot, library) } + const docJSON = JSON.stringify(docObject!) fs.writeFileSync(buildDir + 'docs/' + docObject!.id + '.json', docJSON) + return docObject! + } function tryParseReadme(dirName: string) { diff --git a/packages/__docs__/buildScripts/processFile.mts b/packages/__docs__/buildScripts/processFile.mts index 7e481e06cb..c67f661313 100644 --- a/packages/__docs__/buildScripts/processFile.mts +++ b/packages/__docs__/buildScripts/processFile.mts @@ -28,18 +28,18 @@ import { parseDoc } from './utils/parseDoc.mjs' import { getPathInfo } from './utils/getPathInfo.mjs' import type { LibraryOptions, ProcessedFile } from './DataTypes.mjs' -export function processFile( +export async function processFile( fullPath: string, projectRoot: string, library: LibraryOptions -): ProcessedFile { +): Promise { // eslint-disable-next-line no-console console.info(`Processing ${fullPath}`) const source = fs.readFileSync(fullPath) const dirName = path.dirname(fullPath) || process.cwd() const pathInfo = getPathInfo(fullPath, projectRoot, library) - const doc = parseDoc(fullPath, source, (err: Error) => { + const doc = await parseDoc(fullPath, source, (err: Error) => { console.warn('Error when parsing ', fullPath, ":\n", err.stack) }) const docData: ProcessedFile = { ...doc, ...pathInfo } as ProcessedFile diff --git a/packages/__docs__/buildScripts/utils/getJSDoc.mts b/packages/__docs__/buildScripts/utils/getJSDoc.mts index bef789f3de..5947e1e247 100644 --- a/packages/__docs__/buildScripts/utils/getJSDoc.mts +++ b/packages/__docs__/buildScripts/utils/getJSDoc.mts @@ -26,25 +26,26 @@ import jsdoc from 'jsdoc-api' import type { JsDocResult } from '../DataTypes.mjs' -export function getJSDoc(source: Buffer, error: (err: Error) => void) { +export async function getJSDoc(source: Buffer, error: (err: Error) => void) { // note: JSDoc seems to be abandoned, we should use TypeScript: // https://stackoverflow.com/questions/47429792/is-it-possible-to-get-comments-as-nodes-in-the-ast-using-the-typescript-compiler let doc: Partial = {} try { // JSDoc only creates these sections if the file has a @module or @namespace annotation - let sections: JsDocResult[] = jsdoc - .explainSync({ + let sections: JsDocResult[] = await jsdoc + .explain({ // note: Do not use cache:true here, its buggy configure: './jsdoc.config.json', - source - }) - sections = sections.filter((section) => { - return ( - section.undocumented !== true && - section.access !== 'private' && - section.kind !== 'package' - ) + source: source.toString() }) + + sections = sections.filter((section) => { + return ( + section.undocumented !== true && + section.access !== 'private' && + section.kind !== 'package' + ) + }) const module = sections.filter((section) => section.kind === 'module')[0] || sections[0] || diff --git a/packages/__docs__/buildScripts/utils/getReactDoc.mts b/packages/__docs__/buildScripts/utils/getReactDoc.mts index 6cc808b1c3..e32f4b2aa6 100644 --- a/packages/__docs__/buildScripts/utils/getReactDoc.mts +++ b/packages/__docs__/buildScripts/utils/getReactDoc.mts @@ -33,6 +33,7 @@ export function getReactDoc( error: (err: Error) => void ) { let doc: Documentation | undefined = undefined + try { const parsed = parse( source, @@ -42,6 +43,7 @@ export function getReactDoc( importer: makeFsImporter() } ) + if (parsed.length > 1) { // If a file has multiple exports this will choose the one that has the // same name in its path. diff --git a/packages/__docs__/buildScripts/utils/parseDoc.mts b/packages/__docs__/buildScripts/utils/parseDoc.mts index 73c71861c0..49bad2c805 100644 --- a/packages/__docs__/buildScripts/utils/parseDoc.mts +++ b/packages/__docs__/buildScripts/utils/parseDoc.mts @@ -29,25 +29,28 @@ import path from 'path' import type { JsDocResult, YamlMetaInfo } from '../DataTypes.mjs' import type { Documentation } from 'react-docgen' -export function parseDoc( +export async function parseDoc( resourcePath: string, source: Buffer, errorHandler: (err: Error) => void -): Documentation & YamlMetaInfo & Partial { +): Promise> { const extension = path.extname(resourcePath) const allowedExtensions = ['.js', '.ts', '.tsx'] let doc: Documentation | undefined if (extension === '.md') { - doc = { description: source as unknown as string} + doc = { description: source as unknown as string } } else if (allowedExtensions.includes(extension)) { + doc = getReactDoc(source, resourcePath, errorHandler) + if (!doc || !doc.props) { - doc = getJSDoc(source, errorHandler) + doc = await getJSDoc(source, errorHandler) } + } else { errorHandler(new Error('not allowed extension ' + extension)) - doc = { description: source as unknown as string} + doc = { description: source as unknown as string } } // the YAML description in a JSDoc comment at the top of some files let frontMatter: YamlMetaInfo diff --git a/packages/__docs__/package.json b/packages/__docs__/package.json index d81f8b6479..8ca1e5a9c9 100644 --- a/packages/__docs__/package.json +++ b/packages/__docs__/package.json @@ -134,7 +134,7 @@ "globby": "^14.0.2", "gray-matter": "^4.0.3", "html-webpack-plugin": "^5.6.3", - "jsdoc-api": "^8.1.1", + "jsdoc-api": "^9.3.4", "mkdirp": "^3.0.1", "raw-loader": "^4.0.2", "react-docgen": "^7.1.1", diff --git a/packages/__docs__/webpack.config.mjs b/packages/__docs__/webpack.config.mjs index c11c9ed67c..35f531889d 100644 --- a/packages/__docs__/webpack.config.mjs +++ b/packages/__docs__/webpack.config.mjs @@ -59,15 +59,15 @@ const config = merge(baseConfig, { directory: outputPath, }, host: '0.0.0.0', - onListening: function () { + onListening: async function () { // devServer is watching source files by default and hot reloading the docs page if they are changed // however markdown files (i.e. README.md) need to be recompiled hence the need for chokidar const paths = globbySync(['packages/**/*.md', 'docs/**/*.md'], { cwd: '../../' }).map(p => '../../' + p) chokidar .watch(paths) - .on('change', (evt) => { + .on('change', async (evt) => { const fullPath = resolvePath(import.meta.dirname, evt) - processSingleFile(fullPath) + await processSingleFile(fullPath) }) }, client: {