[docs] Move data grid interfaces to standard API page layout #12016

alexfauquette · 2024-02-09T15:25:58Z

Move interface API pages to the same behavior as other pages:

a json for data
a json for translation
a jsx component to render it

Moving this script to the core package seems tricky, because core has a behavior where each project can be handled independently. Whereas we have interfaces shared between multiple projects and we need to access to them together to do know if properties are available in community, pro; or premium

Still todo:

Examples

GridAPI
- before: https://mui.com/x/api/data-grid/grid-api/
- after: https://deploy-preview-12016--material-ui-x.netlify.app/x/api/data-grid/grid-api/
ColDef
- before: https://mui.com/x/api/data-grid/grid-col-def/
- after: https://deploy-preview-12016--material-ui-x.netlify.app/x/api/data-grid/grid-col-def/

mui-bot · 2024-02-09T15:30:46Z

Deploy preview: https://deploy-preview-12016--material-ui-x.netlify.app/

Generated by 🚫 dangerJS against 2c252af

github-actions · 2024-02-12T14:44:36Z

This pull request has conflicts, please resolve those before we can evaluate the pull request.

netlify · 2024-02-13T13:07:49Z

✅ Deploy Preview for material-ui-x ready!

Name	Link
🔨 Latest commit
🔍 Latest deploy log	https://app.netlify.com/sites/material-ui-x/deploys/65cb6bb82b7eac0e41172e2f
😎 Deploy Preview	https://deploy-preview-12016--material-ui-x.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify site configuration.

github-actions · 2024-02-14T15:12:52Z

This pull request has conflicts, please resolve those before we can evaluate the pull request.

github-actions · 2024-02-20T13:29:37Z

This pull request has conflicts, please resolve those before we can evaluate the pull request.

alexfauquette · 2024-02-20T14:18:20Z

docs/scripts/api/buildInterfacesDocumentation.ts

-    let planImg: string;
-    if (property.projects.includes('x-data-grid')) {
-      planImg = '';
-    } else if (property.projects.includes('x-data-grid-pro')) {
-      planImg =
-        ' [<span class="plan-pro" title="Pro plan"></span>](/x/introduction/licensing/#pro-plan)';
-    } else if (property.projects.includes('x-data-grid-premium')) {
-      planImg =
-        ' [<span class="plan-premium" title="Premium plan"></span>](/x/introduction/licensing/#premium-plan)';
-    } else {
-      throw new Error(`No valid plan found for ${property.name} property in ${object.name}`);
-    }


extracted in getPlanLevel()

alexfauquette · 2024-02-20T14:20:46Z

docs/scripts/api/buildInterfacesDocumentation.ts

-    const formattedName = property.isOptional
-      ? `<span class="prop-name optional">${property.name}<sup><abbr title="optional">?</abbr></sup>${planImg}</span>`
-      : `<span class="prop-name">${property.name}${planImg}</span>`;
-
-    const formattedType = `<span class="prop-type">${escapeCell(property.typeStr)}</span>`;
-
-    const formattedDefaultValue =
-      defaultValue == null ? '' : `<span class="prop-default">${escapeCell(defaultValue)}</span>`;
-
-    const formattedDescription = escapeCell(
-      linkify(property.description, documentedInterfaces, 'markdown'),
-    );
-
-    if (hasDefaultValue) {
-      text += `| ${formattedName} | ${formattedType} | ${formattedDefaultValue} | ${formattedDescription} |\n`;
-    } else {
-      text += `| ${formattedName} | ${formattedType} | ${formattedDescription} |\n`;
-    }
-  });


Formatting and linkify is done when generating the JSON. The rendering aspect (column order, adding plan image, ...) is done in the PropsTable component done in mui/material-ui#41069

alexfauquette · 2024-02-20T14:23:13Z

docs/scripts/api/buildInterfacesDocumentation.ts

  }
+  const demos = tagInfo.text


Because it was markdown rendering, the interface description used markdown format to add links to demo

Here I parse them to extract the url and the name to render

docs/scripts/api/buildInterfacesDocumentation.ts

alexfauquette · 2024-02-20T14:29:46Z

docs/scripts/api/utils.ts

-    .replace(/>/g, '&gt;')
-    .replace(/\|/g, '\\|')
-    .replace(/\r?\n/g, '<br />');
+  return value.replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/\r?\n/g, '<br />');


Remove this escape aspect because it's only for markdown

.replace(/\|/g, '\\|')

github-actions · 2024-02-20T20:55:09Z

This pull request has conflicts, please resolve those before we can evaluate the pull request.

github-actions · 2024-03-20T09:44:26Z

This pull request has conflicts, please resolve those before we can evaluate the pull request.

cherniavskii · 2024-03-28T18:05:02Z

docs/src/modules/components/InterfaceApiPage.js

+      description={description}
+      disableToc={false}
+      toc={[]}
+      location={apiSourceLocation}


The "Edit this page" button is broken – it links to https://github.com/mui/mui-x/settings/master
Previously, we were linking to the .md file, but did it make much sense if the file was autogenerated?

I think we should remove the "Edit this page" button from the interfaces pages.
What do you think?

The link point to https://github.com/mui/mui-x/edit/master/[the location] but the location is an empty string. And https://github.com/mui/mui-x/edit/master/ goes to settings because it's a folder, not a file

Will be fixed with this PR.

mui/material-ui#41702

docs/scripts/api/buildInterfacesDocumentation.ts

cherniavskii · 2024-03-28T18:58:51Z

docs/scripts/api/buildInterfacesDocumentation.ts

@@ -31,14 +31,18 @@ interface ParsedProperty {
  name: string;
  description: string;
  tags: { [tagName: string]: ts.JSDocTagInfo };
-  isOptional: boolean;
+  required: boolean;


PropertiesSection expects the required field.

cherniavskii · 2024-03-28T18:59:11Z

docs/scripts/api/buildInterfacesDocumentation.ts

+          required: property.required,
+        }))
+        .sort((a, b) => {
+          if ((a.required && b.required) || (!a.required && !b.required)) {


To list the required properties first

cherniavskii

Thank you! 👏🏻
These pages look so much better now, especially this one:
Before: https://deploy-preview-12015--material-ui-x.netlify.app/x/api/data-grid/grid-aggregation-function/
After: https://deploy-preview-12016--material-ui-x.netlify.app/x/api/data-grid/grid-aggregation-function/

docs/pages/x/api/data-grid/grid-actions-col-def.json

…into data-grid-interface

Co-authored-by: Andrew Cherniavskyi <andrew@mui.com>

alexfauquette added docs Improvements or additions to the documentation component: data grid This is the name of the generic UI component, not the React module! labels Feb 9, 2024

flaviendelangle changed the title ~~[WIP] Move data grid interfaces to stadard API page layout~~ [WIP] Move data grid interfaces to standard API page layout Feb 9, 2024

alexfauquette force-pushed the data-grid-interface branch from db0b5ce to dee3bdc Compare February 9, 2024 17:48

github-actions bot added the PR: out-of-date The pull request has merge conflicts and can't be merged label Feb 12, 2024

alexfauquette force-pushed the data-grid-interface branch from 5fd3baa to 227b903 Compare February 12, 2024 14:55

github-actions bot removed the PR: out-of-date The pull request has merge conflicts and can't be merged label Feb 12, 2024

alexfauquette requested a review from cherniavskii February 12, 2024 15:23

alexfauquette changed the title ~~[WIP] Move data grid interfaces to standard API page layout~~ [docs] Move data grid interfaces to standard API page layout Feb 12, 2024

alexfauquette marked this pull request as ready for review February 14, 2024 09:35

alexfauquette changed the title ~~[docs] Move data grid interfaces to standard API page layout~~ [docs][Do not merge] Move data grid interfaces to standard API page layout Feb 14, 2024

github-actions bot added the PR: out-of-date The pull request has merge conflicts and can't be merged label Feb 14, 2024

alexfauquette mentioned this pull request Feb 20, 2024

[docs-infra] Support interfaces for X docs mui/material-ui#41069

Merged

github-actions bot added PR: out-of-date The pull request has merge conflicts and can't be merged and removed PR: out-of-date The pull request has merge conflicts and can't be merged labels Feb 20, 2024

github-actions bot removed the PR: out-of-date The pull request has merge conflicts and can't be merged label Feb 20, 2024

alexfauquette commented Feb 20, 2024

View reviewed changes

github-actions bot added the PR: out-of-date The pull request has merge conflicts and can't be merged label Feb 20, 2024

github-actions bot removed the PR: out-of-date The pull request has merge conflicts and can't be merged label Feb 21, 2024

alexfauquette changed the title ~~[docs][Do not merge] Move data grid interfaces to standard API page layout~~ [docs] Move data grid interfaces to standard API page layout Feb 22, 2024

alexfauquette mentioned this pull request Mar 8, 2024

[charts][docs-infra] Document interfaces in dedicated pages #12380

Closed

github-actions bot added the PR: out-of-date The pull request has merge conflicts and can't be merged label Mar 20, 2024

github-actions bot removed the PR: out-of-date The pull request has merge conflicts and can't be merged label Mar 20, 2024

MBilalShafi changed the base branch from next to master March 21, 2024 02:22

alexfauquette force-pushed the data-grid-interface branch from 47e5f89 to d65cfeb Compare March 28, 2024 12:39

alexfauquette added 2 commits March 28, 2024 15:41

modify scripts and render page

702be5e

scripts

6d13431

alexfauquette force-pushed the data-grid-interface branch from d65cfeb to 6d13431 Compare March 28, 2024 14:41

cherniavskii reviewed Mar 28, 2024

View reviewed changes

cherniavskii added 5 commits March 28, 2024 19:43

fix required properties not being reflected in the docs

0aa215b

show required properties first

f386171

fix links

7de8352

docs:api

31c9504

show "optional" labels instead of "required"

ca05573

cherniavskii reviewed Mar 28, 2024

View reviewed changes

cherniavskii approved these changes Mar 28, 2024

View reviewed changes

docs/pages/x/api/data-grid/grid-actions-col-def.json Show resolved Hide resolved

alexfauquette added 2 commits March 29, 2024 10:33

remove md files

bc681d5

Merge branch 'data-grid-interface' of github.com:alexfauquette/mui-x …

2c252af

…into data-grid-interface

alexfauquette merged commit 28da4ca into mui:master Mar 29, 2024
17 checks passed

alexfauquette deleted the data-grid-interface branch March 29, 2024 12:26

joakimtveter pushed a commit to joakimtveter/mui-x that referenced this pull request Jun 6, 2024

[docs] Move data grid interfaces to standard API page layout (mui#12016)

b6a7409

Co-authored-by: Andrew Cherniavskyi <andrew@mui.com>

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[docs] Move data grid interfaces to standard API page layout #12016

[docs] Move data grid interfaces to standard API page layout #12016

alexfauquette commented Feb 9, 2024 •

edited

mui-bot commented Feb 9, 2024 •

edited

github-actions bot commented Feb 12, 2024

netlify bot commented Feb 13, 2024 •

edited

github-actions bot commented Feb 14, 2024

github-actions bot commented Feb 20, 2024

alexfauquette Feb 20, 2024

alexfauquette Feb 20, 2024

alexfauquette Feb 20, 2024

alexfauquette Feb 20, 2024

github-actions bot commented Feb 20, 2024

github-actions bot commented Mar 20, 2024

cherniavskii Mar 28, 2024

alexfauquette Mar 29, 2024

cherniavskii Mar 28, 2024

cherniavskii Mar 28, 2024

cherniavskii left a comment

[docs] Move data grid interfaces to standard API page layout #12016

[docs] Move data grid interfaces to standard API page layout #12016

Conversation

alexfauquette commented Feb 9, 2024 • edited

Still todo:

Examples

mui-bot commented Feb 9, 2024 • edited

github-actions bot commented Feb 12, 2024

netlify bot commented Feb 13, 2024 • edited

✅ Deploy Preview for material-ui-x ready!

github-actions bot commented Feb 14, 2024

github-actions bot commented Feb 20, 2024

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

github-actions bot commented Feb 20, 2024

github-actions bot commented Mar 20, 2024

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

cherniavskii left a comment

Choose a reason for hiding this comment

alexfauquette commented Feb 9, 2024 •

edited

mui-bot commented Feb 9, 2024 •

edited

netlify bot commented Feb 13, 2024 •

edited