[docs-infra] Prepare the infra to extend interface docs to other libr…

…aries
mui · Apr 3, 2024 · f5aeb59 · f5aeb59
1 parent 3d86411
commit f5aeb59
Show file tree

Hide file tree

Showing 4 changed files with 282 additions and 177 deletions.
diff --git a/docs/scripts/api/buildApi.ts b/docs/scripts/api/buildApi.ts
@@ -1,13 +1,21 @@
+/* eslint-disable no-await-in-loop */
 import * as yargs from 'yargs';
 import path from 'path';
 import fs from 'fs';
 import * as prettier from 'prettier';
 import kebabCase from 'lodash/kebabCase';
-import buildInterfacesDocumentation from './buildInterfacesDocumentation';
+import {
+  buildApiInterfacesJson,
+  buildInterfacesDocumentationPage,
+} from './buildInterfacesDocumentation';
 import buildExportsDocumentation from './buildExportsDocumentation';
 import buildGridSelectorsDocumentation from './buildGridSelectorsDocumentation';
 import buildGridEventsDocumentation from './buildGridEventsDocumentation';
-import { createXTypeScriptProjects } from '../createXTypeScriptProjects';
+import {
+  XProjectNames,
+  XTypeScriptProjects,
+  createXTypeScriptProjects,
+} from '../createXTypeScriptProjects';
 import { DocumentedInterfaces } from './utils';
 
 const DEFAULT_PRETTIER_CONFIG_PATH = path.join(process.cwd(), 'prettier.config.js');
@@ -47,6 +55,7 @@ const bracketsRegexp = /\[\[([^\]]+)\]\]/g;
 export default async function linkifyTranslation(
   directory: string,
   documentedInterfaces: DocumentedInterfaces,
+  folder: string,
 ) {
   const items = fs.readdirSync(directory);
 
@@ -55,7 +64,7 @@ export default async function linkifyTranslation(
       const itemPath = path.resolve(directory, item);
 
       if (fs.statSync(itemPath).isDirectory()) {
-        await linkifyTranslation(itemPath, documentedInterfaces);
+        await linkifyTranslation(itemPath, documentedInterfaces, folder);
         return;
       }
 
@@ -69,7 +78,7 @@ export default async function linkifyTranslation(
         if (!documentedInterfaces.get(content)) {
           return content;
         }
-        const url = `/x/api/data-grid/${kebabCase(content)}/`;
+        const url = `/x/api/${folder}/${kebabCase(content)}/`;
         return `<a href='${url}'>${content}</a>`;
       });
 
@@ -78,29 +87,111 @@ export default async function linkifyTranslation(
   );
 }
 
+const specialAPIs: { folder: string; packages: XProjectNames[]; documentedInterfaces: string[] }[] =
+  [
+    {
+      folder: 'data-grid',
+      packages: ['x-data-grid', 'x-data-grid-pro', 'x-data-grid-premium', 'x-data-grid-generator'],
+      documentedInterfaces: [
+        // apiRef
+        'GridApi',
+
+        // Params
+        'GridCellParams',
+        'GridRowParams',
+        'GridRowClassNameParams',
+        'GridRowSpacingParams',
+        'GridExportStateParams',
+
+        // Others
+        'GridColDef',
+        'GridSingleSelectColDef',
+        'GridActionsColDef',
+        'GridCsvExportOptions',
+        'GridPrintExportOptions',
+        'GridExcelExportOptions',
+
+        // Filters
+        'GridFilterModel',
+        'GridFilterItem',
+        'GridFilterOperator',
+
+        // Aggregation
+        'GridAggregationFunction',
+      ],
+    },
+    // {
+    //   folder: 'charts',
+    //   packages: ['x-charts'],
+    // },
+  ];
 async function run() {
   const projects = createXTypeScriptProjects();
 
   // Create documentation folder if it does not exist
   const apiPagesFolder = path.resolve('./docs/pages/x/api');
-  const dataGridTranslationFolder = path.resolve('./docs/translations/api-docs/data-grid/');
-
-  const documentedInterfaces = await buildInterfacesDocumentation({
-    projects,
-    apiPagesFolder,
-  });
 
-  await linkifyTranslation(dataGridTranslationFolder, documentedInterfaces);
+  // eslint-disable-next-line no-restricted-syntax
+  for (const { folder, packages, documentedInterfaces } of specialAPIs) {
+    const subProjects: XTypeScriptProjects = new Map();
+
+    packages.forEach((pck) => {
+      subProjects.set(pck, projects.get(pck)!);
+    });
+
+    // Create translation folder if it does not exist
+    const translationFolder = path.resolve(`./docs/translations/api-docs/${folder}/`);
+
+    const interfacesWithDedicatedPage = await buildInterfacesDocumentationPage({
+      projects: subProjects,
+      translationPagesDirectory: `docs/translations/api-docs/${folder}`,
+      importTranslationPagesDirectory: `docsx/translations/api-docs/${folder}`,
+      apiPagesDirectory: path.join(process.cwd(), `docs/pages/x/api/${folder}`),
+      folder,
+      interfaces: documentedInterfaces,
+    });
+
+    await linkifyTranslation(translationFolder, interfacesWithDedicatedPage, folder);
+
+    if (folder === 'data-grid') {
+      // Generate JSON for some API inerfaces rendered in the `<ApiDocs />` components.
+      // This is API insterted inside some demo pages, and not dedicated pages.
+      await buildApiInterfacesJson({
+        projects: subProjects,
+        apiPagesFolder,
+        folder,
+        interfaces: [
+          'GridCellSelectionApi',
+          'GridColumnPinningApi',
+          'GridColumnResizeApi',
+          'GridCsvExportApi',
+          'GridDetailPanelApi',
+          'GridEditingApi',
+          'GridExcelExportApi',
+          'GridFilterApi',
+          'GridPaginationApi',
+          'GridPrintExportApi',
+          'GridRowGroupingApi',
+          'GridRowMultiSelectionApi',
+          'GridRowSelectionApi',
+          'GridScrollApi',
+          'GridSortApi',
+          'GridVirtualizationApi',
+        ],
+        interfacesWithDedicatedPage,
+      });
 
-  await buildGridEventsDocumentation({
-    projects,
-    documentedInterfaces,
-  });
+      await buildGridEventsDocumentation({
+        projects: subProjects,
+        interfacesWithDedicatedPage,
+      });
 
-  await buildGridSelectorsDocumentation({
-    project: projects.get('x-data-grid-premium')!,
-    apiPagesFolder,
-  });
+      await buildGridSelectorsDocumentation({
+        project: projects.get('x-data-grid-premium')!,
+        apiPagesFolder,
+      });
+    }
+  }
 
   buildExportsDocumentation({
     projects,

diff --git a/docs/scripts/api/buildGridEventsDocumentation.ts b/docs/scripts/api/buildGridEventsDocumentation.ts
@@ -13,15 +13,15 @@ import { XProjectNames, XTypeScriptProjects } from '../createXTypeScriptProjects
 
 interface BuildEventsDocumentationOptions {
   projects: XTypeScriptProjects;
-  documentedInterfaces: DocumentedInterfaces;
+  interfacesWithDedicatedPage: DocumentedInterfaces;
 }
 
 const GRID_PROJECTS: XProjectNames[] = ['x-data-grid', 'x-data-grid-pro', 'x-data-grid-premium'];
 
 export default async function buildGridEventsDocumentation(
   options: BuildEventsDocumentationOptions,
 ) {
-  const { projects, documentedInterfaces } = options;
+  const { projects, interfacesWithDedicatedPage } = options;
 
   const events: {
     [eventName: string]: {
@@ -61,8 +61,9 @@ export default async function buildGridEventsDocumentation(
 
           const description = linkify(
             getSymbolDescription(event, project),
-            documentedInterfaces,
+            interfacesWithDedicatedPage,
             'html',
+            'data-grid',
           );
 
           const eventParams: { [key: string]: string } = {};
@@ -80,7 +81,7 @@ export default async function buildGridEventsDocumentation(
             projects: [project.name],
             name: event.name,
             description: renderMarkdown(description),
-            params: linkify(eventParams.params, documentedInterfaces, 'html'),
+            params: linkify(eventParams.params, interfacesWithDedicatedPage, 'html', 'data-grid'),
             event: `MuiEvent<${eventParams.event ?? '{}'}>`,
           };
         }