From 8e177fa6db8b2bf4aa939548a4467197dd7f788a Mon Sep 17 00:00:00 2001 From: marcelovicentegc Date: Tue, 21 Nov 2023 21:10:30 -0300 Subject: [PATCH] feat: docs generator --- .eslintrc | 3 +- .gitignore | 3 ++ package.json | 3 ++ pnpm-lock.yaml | 43 ++++++++++++++++++++-- scripts/format-docs.js | 83 ++++++++++++++++++++++++++++++++++++++++++ typedoc.json | 13 +++++++ 6 files changed, 143 insertions(+), 5 deletions(-) create mode 100644 scripts/format-docs.js create mode 100644 typedoc.json diff --git a/.eslintrc b/.eslintrc index a45aa95b65..dd4f424a5a 100644 --- a/.eslintrc +++ b/.eslintrc @@ -9,7 +9,8 @@ ".vscode/", ".cache/", "__mocks__/", - "__generated__/" + "__generated__/", + "scripts/format-docs.js" ], "env": { "es2022": true diff --git a/.gitignore b/.gitignore index 0f830b24dc..ef6cd65386 100644 --- a/.gitignore +++ b/.gitignore @@ -82,3 +82,6 @@ out # File system stuff **/.DS_Store + +# Auto-generated documentation +__tmpDocs \ No newline at end of file diff --git a/package.json b/package.json index a5dd7f7da7..683d459305 100644 --- a/package.json +++ b/package.json @@ -30,6 +30,7 @@ "build:storybook": "pnpm build && pnpm storybook build", "chromatic": "chromatic --exit-zero-on-changes --build-script-name=build:storybook", "docs": "npm --prefix packages/admin-ui-docs run start", + "generate-docs": "typedoc --plugin typedoc-plugin-markdown && node scripts/format-docs.js", "next-docs": "npm --prefix packages/next-docs run dev", "build:docs": "npm --prefix packages/admin-ui-docs run build-docs", "build:next-docs": "npm --prefix packages/next-docs run build-docs", @@ -129,6 +130,8 @@ "storybook": "^7.5.3", "tslib": "2.6.2", "turbo": "1.4.3", + "typedoc": "^0.25.3", + "typedoc-plugin-markdown": "^3.17.1", "typescript": "4.9.5", "url-loader": "^4.1.0", "vite": "4.3.9", diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index 247194ef98..042ef845b2 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -260,6 +260,12 @@ importers: turbo: specifier: 1.4.3 version: 1.4.3 + typedoc: + specifier: ^0.25.3 + version: 0.25.3(typescript@4.9.5) + typedoc-plugin-markdown: + specifier: ^3.17.1 + version: 3.17.1(typedoc@0.25.3) typescript: specifier: 4.9.5 version: 4.9.5 @@ -12100,7 +12106,6 @@ packages: /ansi-sequence-parser@1.1.0: resolution: {integrity: sha512-lEm8mt52to2fT8GhciPCGeCXACSz2UwIN4X2e2LJSnZ5uAbn2/dsYdOmUXq0AtWS5cpAupysIneExOgH0Vd2TQ==} - dev: false /ansi-styles@2.2.1: resolution: {integrity: sha512-kmCevFghRiWM7HB5zTPULl4r9bVFSWjz62MhqizDGUrq2NWuNMQyuv4tHHoKJHs69M/MF64lEcHdYIocrdWQYA==} @@ -20628,6 +20633,10 @@ packages: engines: {node: '>=12'} dev: true + /lunr@2.3.9: + resolution: {integrity: sha512-zTU3DaZaF3Rt9rhN3uBMGQD3dD2/vFQqnvZCDv4dl5iOzq2IZQqTxu90r4E5J+nP70J3ilqVCrbho2eWaeW8Ow==} + dev: true + /lz-string@1.5.0: resolution: {integrity: sha512-h5bgJWpxJNswbU7qCrV0tIKQCaS3blPDrqKWx+QxzuzL1zGUzij9XCWLrSLsJPu5t+eWA/ycetzYAO5IOMcWAQ==} hasBin: true @@ -20762,6 +20771,12 @@ packages: react: 18.2.0 dev: true + /marked@4.3.0: + resolution: {integrity: sha512-PRsaiG84bK+AMvxziE/lCFss8juXjNaWzVbN5tXAm4XjeaS9NAHhop+PjQxz2A9h8Q4M/xGmzP8vqNwy6JeK0A==} + engines: {node: '>= 12'} + hasBin: true + dev: true + /match-sorter@6.3.1: resolution: {integrity: sha512-mxybbo3pPNuA+ZuCUhm5bwNkXrJTbsk5VWbR5wiwz/GC6LIiegBGn2w3O08UG/jdbYLinw51fSQ5xNU1U3MgBw==} dependencies: @@ -25887,7 +25902,6 @@ packages: jsonc-parser: 3.2.0 vscode-oniguruma: 1.7.0 vscode-textmate: 8.0.0 - dev: false /side-channel@1.0.4: resolution: {integrity: sha512-q5XPytqFEIKHkGdiMIrY10mvLRvnQh42/+GoBlFW3b2LXLE2xxJpZFdm94we0BaoV3RwJyGqg5wS7epxTv0Zvw==} @@ -27581,6 +27595,29 @@ packages: resolution: {integrity: sha512-/aCDEGatGvZ2BIk+HmLf4ifCJFwvKFNb9/JeZPMulfgFracn9QFcAf5GO8B/mweUjSoblS5In0cWhqpfs/5PQA==} dev: true + /typedoc-plugin-markdown@3.17.1(typedoc@0.25.3): + resolution: {integrity: sha512-QzdU3fj0Kzw2XSdoL15ExLASt2WPqD7FbLeaqwT70+XjKyTshBnUlQA5nNREO1C2P8Uen0CDjsBLMsCQ+zd0lw==} + peerDependencies: + typedoc: '>=0.24.0' + dependencies: + handlebars: 4.7.7 + typedoc: 0.25.3(typescript@4.9.5) + dev: true + + /typedoc@0.25.3(typescript@4.9.5): + resolution: {integrity: sha512-Ow8Bo7uY1Lwy7GTmphRIMEo6IOZ+yYUyrc8n5KXIZg1svpqhZSWgni2ZrDhe+wLosFS8yswowUzljTAV/3jmWw==} + engines: {node: '>= 16'} + hasBin: true + peerDependencies: + typescript: 4.6.x || 4.7.x || 4.8.x || 4.9.x || 5.0.x || 5.1.x || 5.2.x + dependencies: + lunr: 2.3.9 + marked: 4.3.0 + minimatch: 9.0.3 + shiki: 0.14.3 + typescript: 4.9.5 + dev: true + /typescript-service@2.0.3: resolution: {integrity: sha512-FzRlqRp965UBzGvGwc6rbeko84jLILZrHf++I4cN8usZUB7F8Lh8/WDiCOUvy2l5os+jBWEz4fbYkkj1DhYJcw==} engines: {node: '>=6', npm: '>=3'} @@ -28463,11 +28500,9 @@ packages: /vscode-oniguruma@1.7.0: resolution: {integrity: sha512-L9WMGRfrjOhgHSdOYgCt/yRMsXzLDJSL7BPrOZt73gU0iWO4mpqzqQzOz5srxqTvMBaR0XZTSrVWo4j55Rc6cA==} - dev: false /vscode-textmate@8.0.0: resolution: {integrity: sha512-AFbieoL7a5LMqcnOF04ji+rpXadgOXnZsxQr//r83kLPr7biP7am3g9zbaZIaBGwBRWeSvoMD4mgPdX3e4NWBg==} - dev: false /w3c-keyname@2.2.6: resolution: {integrity: sha512-f+fciywl1SJEniZHD6H+kUO8gOnwIr7f4ijKA6+ZvJFjeGi1r4PDLl53Ayud9O/rk64RqgoQine0feoeOU0kXg==} diff --git a/scripts/format-docs.js b/scripts/format-docs.js new file mode 100644 index 0000000000..bb3e6d05e5 --- /dev/null +++ b/scripts/format-docs.js @@ -0,0 +1,83 @@ +const fs = require('fs') +const prettier = require('prettier') + +function splitIntoMultipleFiles() { + const cwd = process.cwd() + + const rootFile = fs.readFileSync(`${cwd}/__tmpDocs/modules.md`, 'utf8') + // typedoc-plugin-markdown generates a single file with all the docs separated by "___" + const files = rootFile.split('___') + + for (const file of files) { + try { + const content = file.split('\n') + const componentName = content + // Find the line that starts with "###", which is the component/method/hook name + .find((line) => line.startsWith('###')) + .replace('###', '') + .trim() + + // Means that this is a component + const isPascalCase = /^[A-Z][a-zA-Z0-9]*$/.test(componentName) + + // Means that this is a hook, matches camelCase methods starting with "use" + const isHook = /^use[A-Z][a-zA-Z0-9]*$/.test(componentName) + + if (isHook) { + const kebabCaseName = componentName + .replace(/([a-z0-9])([A-Z])/g, '$1-$2') + .toLowerCase() + + const folderPath = `${cwd}/__tmpDocs/hooks/${kebabCaseName}` + fs.mkdirSync(folderPath, { + recursive: true, + }) + + const filePath = `${folderPath}/code.mdx` + fs.writeFileSync(filePath, file) + prettify(filePath) + + continue + } + + if (isPascalCase) { + const kebabCaseName = componentName + .replace(/([a-z0-9])([A-Z])/g, '$1-$2') + .toLowerCase() + + const folderPath = `${cwd}/__tmpDocs/components/${kebabCaseName}` + fs.mkdirSync(folderPath, { + recursive: true, + }) + + const filePath = `${folderPath}/code.mdx` + fs.writeFileSync(filePath, file) + + prettify(filePath) + + continue + } + + const filePath = `${cwd}/__tmpDocs/${componentName}.md` + fs.writeFileSync(filePath, file) + prettify(filePath) + } catch (error) { + console.error(error) + } + } +} + +function prettify(filePath) { + const prettierConfigPath = require.resolve('../.prettierrc') + const prettierConfig = require(prettierConfigPath) + const prettierOptions = { + ...prettierConfig, + parser: 'markdown', + } + + const file = fs.readFileSync(filePath, 'utf8') + const formatted = prettier.format(file, prettierOptions) + fs.writeFileSync(filePath, formatted) +} + +splitIntoMultipleFiles() diff --git a/typedoc.json b/typedoc.json new file mode 100644 index 0000000000..f69a46cce4 --- /dev/null +++ b/typedoc.json @@ -0,0 +1,13 @@ +{ + "$schema": "https://typedoc.org/schema.json", + "entryPoints": [ + "packages/components/src/index.ts", + "packages/raccoon-next/src/index.ts", + "packages/raccoon-io/src/index.ts" + ], + "exclude": [ + "packages/components/src/**/*+(index|.vitest|.e2e|.test|.stories).(ts|tsx)" + ], + "tsconfig": "packages/components/tsconfig.json", + "out": "__tmpDocs" +}