Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

[docs-infra] Prepare infra to document charts interfaces #12653

Merged
merged 3 commits into from
Apr 17, 2024
Merged

[docs-infra] Prepare infra to document charts interfaces #12653

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
f5aeb59
[docs-infra] Prepare the infra to extend interface docs to other libr…
alexfauquette Apr 3, 2024
af44b4d
fix eslint
alexfauquette Apr 5, 2024
685c41c
move config
alexfauquette Apr 5, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
129 changes: 110 additions & 19 deletions docs/scripts/api/buildApi.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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');
Expand Down Expand Up @@ -47,6 +55,7 @@ const bracketsRegexp = /\[\[([^\]]+)\]\]/g;
export default async function linkifyTranslation(
directory: string,
documentedInterfaces: DocumentedInterfaces,
folder: string,
) {
const items = fs.readdirSync(directory);

Expand All @@ -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;
}

Expand All @@ -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>`;
});

Expand All @@ -78,29 +87,111 @@ export default async function linkifyTranslation(
);
}

const specialAPIs: { folder: string; packages: XProjectNames[]; documentedInterfaces: string[] }[] =
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Would it make sense to define those in a new file next to getComponentInfo in buildApiDocs?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

  • make sens: yes
  • feasible: no

😅

The API build is done in two times in X docs:

yarn docs:api:build && yarn docs:api:buildX
  1. The generation of components API done by the pipeline we import from core and defined by those files in buildApiDocs
  2. The one specific to X that generate files for the events, selectors, interfaces and API

I tried once to merge those two scripts. But it's... complicated.

The core script is written without taking care about project relations, because each component can be done independently.
The X script is more project related, because knowing in which project properties are defined implies their pricing level (community, pro, premium) Plus when generating pages to document interfaces, we update an object to know all the pages generated, and then override the translation such that [[GridAPI]] is transformed in a link to the API page of the grid api.

In brief, core does

for project in projects:
  for component in project:
	generateApiPage(component)

And X does

generatedPages = {}
for interface in interfacesToDocument:
  generateApiPage(interface, projects, generatedPages)

for project in dataGridProjects:
  for apiInterface in project:
	generateApiPage(apiInterface)

for translation in treanslationFiles:
  updateLinks(translation, generatedPages)

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Then maybe moving it to createXTypeScriptProjects

Basically my issue is to have a new project-related config inside a file that people might struggle to find.
The more we centralize, the better I am 😆

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The more we centralize, the better I am 😆

That's a political opinion? 😇😆

Then maybe moving it to createXTypeScriptProjects

The file name is not well adapt, but it will make those parameters more visible 👍

[
{
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,
Expand Down
9 changes: 5 additions & 4 deletions docs/scripts/api/buildGridEventsDocumentation.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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]: {
Expand Down Expand Up @@ -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 } = {};
Expand All @@ -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 ?? '{}'}>`,
};
}
Expand Down