[core] Clean up the API docs generation scripts (mui#35244)

docs/config.d.ts

@@ -0,0 +1,2 @@
+// eslint-disable-next-line import/prefer-default-export
+export const LANGUAGES: string[];

docs/config.js

@@ -0,0 +1,6 @@
+module.exports = {
+ /**
+ * Valid languages to server-side render in production
+ */
+ LANGUAGES: ['en', 'zh', 'pt'],
+};

docs/package.json

@@ -60,7 +60,6 @@
  "@types/react-virtualized": "^9.21.21",
  "@types/react-window": "^1.8.5",
  "@types/styled-components": "5.1.26",
- "ast-types": "^0.14.2",
  "autoprefixer": "^10.4.13",
  "autosuggest-highlight": "^3.3.4",
  "babel-plugin-module-resolver": "^4.1.0",
@@ -75,7 +74,6 @@
  "css-mediaquery": "^0.1.2",
  "date-fns": "^2.29.3",
  "date-fns-jalali": "^2.21.3-1",
- "doctrine": "^3.0.0",
  "exceljs": "^4.3.0",
  "express": "^4.18.2",
  "fg-loadcss": "^3.1.0",
@@ -96,7 +94,6 @@
  "postcss": "^8.4.19",
  "prop-types": "^15.8.1",
  "react": "^18.2.0",
- "react-docgen": "^5.4.3",
  "react-dom": "^18.2.0",
  "react-draggable": "^4.4.5",
  "react-final-form": "^6.5.9",
@@ -112,7 +109,6 @@
  "react-transition-group": "^4.4.5",
  "react-virtualized": "^9.22.3",
  "react-window": "^1.8.8",
- "recast": "^0.21.5",
  "recharts": "2.1.16",
  "rimraf": "^3.0.2",
  "styled-components": "^5.3.6",

docs/packages/markdown/index.d.ts

@@ -0,0 +1,18 @@
+interface TableOfContentsEntry {
+ children: TableOfContentsEntry;
+ hash: string;
+ level: number;
+ text: string;
+}
+
+export function createRender(context: {
+ headingHashes: Record<string, string>;
+ toc: TableOfContentsEntry[];
+ userLanguage: string;
+}): (markdown: string) => string;
+
+export function getHeaders(markdown: string): Record<string, string | string[]>;
+
+export function getTitle(markdown: string): string;
+
+export function renderInline(markdown: string): string;

docs/packages/markdown/package.json

@@ -3,6 +3,7 @@
  "version": "5.0.0",
  "private": true,
  "main": "./index.js",
+ "types": "./index.d.ts",
  "exports": {
  ".": "./index.js",
  "./loader": "./loader.js",

docs/packages/markdown/parseMarkdown.js

@@ -130,7 +130,7 @@ function getTitle(markdown) {
  const matches = markdown.match(titleRegExp);
 
  if (matches === null) {
- return undefined;
+ return '';
  }
 
  return matches[1].replace(/`/g, '');

docs/packages/markdown/prism.d.ts

@@ -0,0 +1 @@
+export default function highlight(code: string, language: string): string;

docs/scripts/formattedTSDemos.js

@@ -17,7 +17,7 @@ const babel = require('@babel/core');
 const prettier = require('prettier');
 const typescriptToProptypes = require('typescript-to-proptypes');
 const yargs = require('yargs');
-const { fixBabelGeneratorIssues, fixLineEndings } = require('./helpers');
+const { fixBabelGeneratorIssues, fixLineEndings } = require('@mui-internal/docs-utilities');
 
 const tsConfig = typescriptToProptypes.loadConfig(path.resolve(__dirname, '../tsconfig.json'));
 

docs/scripts/tsconfig.json

@@ -1,6 +1,6 @@
 {
  "extends": "../../tsconfig.json",
- "include": ["../types/react-docgen.d.ts", "buildApi.ts", "i18n.js", "ApiBuilders/**/*"],
+ "include": ["*.ts", "i18n.js"],
  "compilerOptions": {
  "allowJs": true,
  "isolatedModules": true,
@@ -10,6 +10,5 @@
  "skipLibCheck": true,
  "esModuleInterop": true,
  "types": ["node"]
- },
- "exclude": ["node_modules"]
+ }
 }

docs/src/modules/constants.js

@@ -1,11 +1,10 @@
+const { LANGUAGES } = require('../../config');
+
 const CODE_VARIANTS = {
  JS: 'JS',
  TS: 'TS',
 };
 
-// Valid languages to server-side render in production
-const LANGUAGES = ['en'];
-
 // Server side rendered languages
 const LANGUAGES_SSR = ['en'];
 

docs/src/modules/utils/find.js

@@ -1,80 +1,6 @@
 const fs = require('fs');
 const path = require('path');
 
-/**
- * Returns the markdowns of the documentation in a flat array.
- * @param {string} [directory]
- * @param {Array<{ filename: string, pathname: string }>} [pagesMarkdown]
- * @returns {Array<{ filename: string, pathname: string }>}
- */
-function findPagesMarkdownNew(
- directory = path.resolve(__dirname, '../../../data'),
- pagesMarkdown = [],
-) {
- const items = fs.readdirSync(directory);
-
- items.forEach((item) => {
- const itemPath = path.resolve(directory, item);
-
- if (fs.statSync(itemPath).isDirectory()) {
- findPagesMarkdownNew(itemPath, pagesMarkdown);
- return;
- }
-
- if (!/\.md$/.test(item) || /-(zh|pt)\.md/.test(item)) {
- // neglect translation markdown
- return;
- }
-
- let pathname = itemPath
- .replace(new RegExp(`\\${path.sep}`, 'g'), '/')
- .replace(/^.*\/data/, '')
- .replace('.md', '');
-
- // Remove the last pathname segment.
- pathname = pathname.split('/').slice(0, 4).join('/');
-
- pagesMarkdown.push({
- // Relative location in the path (URL) system.
- pathname,
- // Relative location in the file system.
- filename: itemPath,
- });
- });
-
- return pagesMarkdown;
-}
-
-const componentRegex = /^(Unstable_)?([A-Z][a-z]+)+\.(js|tsx)/;
-
-/**
- * Returns the component source in a flat array.
- * @param {string} directory
- * @param {Array<{ filename: string }>} components
- */
-function findComponents(directory, components = []) {
- const items = fs.readdirSync(directory);
-
- items.forEach((item) => {
- const itemPath = path.resolve(directory, item);
-
- if (fs.statSync(itemPath).isDirectory()) {
- findComponents(itemPath, components);
- return;
- }
-
- if (!componentRegex.test(item)) {
- return;
- }
-
- components.push({
- filename: itemPath,
- });
- });
-
- return components;
-}
-
 const pageRegex = /(\.js|\.tsx)$/;
 const blackList = ['/.eslintrc', '/_document', '/_app'];
 
@@ -157,6 +83,4 @@ function findPages(
 
 module.exports = {
  findPages,
- findPagesMarkdownNew,
- findComponents,
 };

docs/src/modules/utils/helpers.ts

@@ -106,8 +106,3 @@ export function pathnameToLanguage(pathname: string): {
  canonicalPathname,
  };
 }
-
-export function escapeCell(value: string): string {
- // As the pipe is use for the table structure
- return value.replace(/</g, '&lt;').replace(/`&lt;/g, '`<').replace(/\|/g, '\\|');
-}

package.json

@@ -14,7 +14,7 @@
  "release:publish:dry-run": "lerna publish from-package --dist-tag latest --contents build --registry=\"http://localhost:4873/\"",
  "release:tag": "node scripts/releaseTag.mjs",
  "docs:api": "rimraf ./docs/pages/**/api-docs ./docs/pages/**/api && yarn docs:api:build",
- "docs:api:build": "cross-env BABEL_ENV=development __NEXT_EXPORT_TRAILING_SLASH=true babel-node --extensions \".tsx,.ts,.js\" ./docs/scripts/buildApi.ts",
+ "docs:api:build": "ts-node ./packages/api-docs-builder/buildApi.ts",
  "docs:build": "yarn workspace docs build",
  "docs:build-sw": "yarn workspace docs build-sw",
  "docs:build-color-preview": "babel-node scripts/buildColorTypes",
@@ -100,6 +100,7 @@
  "@types/jsdom": "^20.0.1",
  "@types/lodash": "^4.14.190",
  "@types/mocha": "^10.0.0",
+ "@types/node": "^18.11.9",
  "@types/prettier": "^2.7.1",
  "@types/react": "^18.0.25",
  "@types/react-is": "^17.0.3",

docs/scripts/ApiBuilders/ComponentApiBuilder.ts → packages/api-docs-builder/ApiBuilders/ComponentApiBuilder.ts

@@ -11,20 +11,19 @@ import remarkVisit from 'unist-util-visit';
 import { Link } from 'mdast';
 import { defaultHandlers, parse as docgenParse, ReactDocgenApi } from 'react-docgen';
 import { unstable_generateUtilityClass as generateUtilityClass } from '@mui/utils';
-import muiDefaultPropsHandler from 'docs/src/modules/utils/defaultPropsHandler';
-import { LANGUAGES } from 'docs/src/modules/constants';
-import parseTest from 'docs/src/modules/utils/parseTest';
-import generatePropTypeDescription, {
- getChained,
-} from 'docs/src/modules/utils/generatePropTypeDescription';
 import { renderInline as renderMarkdownInline } from '@mui/markdown';
+import { getUnstyledFilename } from '@mui-internal/docs-utilities';
+import * as ttp from 'typescript-to-proptypes';
+import { LANGUAGES } from 'docs/config';
+
+import muiDefaultPropsHandler from '../utils/defaultPropsHandler';
+import parseTest from '../utils/parseTest';
+import generatePropTypeDescription, { getChained } from '../utils/generatePropTypeDescription';
 import createDescribeableProp, {
  DescribeablePropDescriptor,
-} from 'docs/src/modules/utils/createDescribeableProp';
-import generatePropDescription from 'docs/src/modules/utils/generatePropDescription';
-import parseStyles, { Styles } from 'docs/src/modules/utils/parseStyles';
-import * as ttp from 'typescript-to-proptypes';
-import { getUnstyledFilename } from '../helpers';
+} from '../utils/createDescribeableProp';
+import generatePropDescription from '../utils/generatePropDescription';
+import parseStyles, { Styles } from '../utils/parseStyles';
 import { ComponentInfo } from '../buildApiUtils';
 
 const DEFAULT_PRETTIER_CONFIG_PATH = path.join(process.cwd(), 'prettier.config.js');

docs/scripts/buildApi.ts → packages/api-docs-builder/buildApi.ts

@@ -4,18 +4,18 @@ import path from 'path';
 import kebabCase from 'lodash/kebabCase';
 import * as yargs from 'yargs';
 import * as ttp from 'typescript-to-proptypes';
-import { findComponents } from 'docs/src/modules/utils/find';
+import findComponents from './utils/findComponents';
 import {
  ComponentInfo,
  getMaterialComponentInfo,
  getBaseComponentInfo,
  getSystemComponentInfo,
  extractApiPage,
-} from 'docs/scripts/buildApiUtils';
+} from './buildApiUtils';
 import generateComponentApi, {
  writePrettifiedFile,
  ReactApi,
-} from 'docs/scripts/ApiBuilders/ComponentApiBuilder';
+} from './ApiBuilders/ComponentApiBuilder';
 
 const apiDocsTranslationsDirectory = path.resolve('docs', 'translations', 'api-docs');
 
@@ -66,7 +66,7 @@ const getAllFiles = (dirPath: string, arrayOfFiles: string[] = []) => {
 
 function findApiPages(relativeFolder: string) {
  let pages: Array<{ pathname: string }> = [];
- let filePaths = [];
+ let filePaths: string[] = [];
  try {
  filePaths = getAllFiles(path.join(process.cwd(), relativeFolder));
  } catch (error) {

docs/scripts/buildApiUtils.ts → packages/api-docs-builder/buildApiUtils.ts

@@ -2,9 +2,9 @@ import fs from 'fs';
 import path from 'path';
 import kebabCase from 'lodash/kebabCase';
 import { getHeaders, getTitle } from '@mui/markdown';
-import { findPagesMarkdownNew } from 'docs/src/modules/utils/find';
-import { getLineFeed } from 'docs/scripts/helpers';
-import { replaceComponentLinks } from 'docs/src/modules/utils/replaceUrl';
+import { getLineFeed } from '@mui-internal/docs-utilities';
+import { replaceComponentLinks } from './utils/replaceUrl';
+import findPagesMarkdownNew from './utils/findPagesMarkdown';
 
 const systemComponents = fs
  .readdirSync(path.resolve('packages', 'mui-system', 'src'))

packages/api-docs-builder/package.json

@@ -0,0 +1,28 @@
+{
+ "name": "@mui-internal/api-docs-builder",
+ "version": "1.0.0",
+ "private": "true",
+ "main": "./buildApi.ts",
+ "scripts": {
+ "typescript": "tsc -p tsconfig.json"
+ },
+ "dependencies": {
+ "@babel/core": "^7.20.2",
+ "@mui-internal/docs-utilities": "*",
+ "@mui/markdown": "*",
+ "ast-types": "^0.14.2",
+ "doctrine": "^3.0.0",
+ "lodash": "^4.17.21",
+ "react-docgen": "^5.4.3",
+ "recast": "^0.21.5",
+ "typescript-to-proptypes": "*",
+ "yargs": "^17.6.2"
+ },
+ "devDependencies": {
+ "@types/mocha": "^10.0.0",
+ "@types/node": "^18.11.9",
+ "chai": "^4.3.7",
+ "sinon": "^14.0.2",
+ "typescript": "^4.9.3"
+ }
+}

packages/api-docs-builder/tsconfig.json

@@ -0,0 +1,22 @@
+{
+ "compilerOptions": {
+ "allowJs": true,
+ "isolatedModules": true,
+ "noEmit": true,
+ "noUnusedLocals": true,
+ "resolveJsonModule": true,
+ "skipLibCheck": true,
+ "esModuleInterop": true,
+ "types": ["node", "mocha"],
+ "target": "ES2020",
+ "module": "CommonJS",
+ "moduleResolution": "node",
+ "strict": true,
+ "baseUrl": "./",
+ "paths": {
+ "react-docgen": ["./react-docgen.d.ts"]
+ }
+ },
+ "include": ["./**/*.ts", "./**/*.js"],
+ "exclude": ["node_modules"]
+}