[docs] Automatically generate API docs #1529

m4theushw · 2021-04-30T18:16:46Z

This PR covers the automatic generation of the API pages using typedoc.

Preview:
https://deploy-preview-1529--material-ui-x.netlify.app/api/data-grid/

Closes #446
To be merged after #1572

Summary of changes

All API pages of the DataGrid are not in a new submenu under Components API.

Added a page to group the exports into categories. This is what users looking for the DataGrid component will see now.
Added a page describing how to subscribe to events. This page also contains a table automatically populated with all the events. I had to do some workarounds to get the same styling from the component API page here. The worst part I think is using the MarkdownElement (a component from the docs) inside a demo, but users can't fork the demo so maybe we can live with that. We could separate the events into groups if necessary.
Generated API pages for the GridApi, GridColDef, GridCellParams and GridRowParams. Which other APIs should we have documentation?

TODO:

Docs for events (https://ag-grid.com/javascript-grid/grid-events/)
Index page (https://www.telerik.com/kendo-react-ui/components/grid/api/)
Add missing renders in generateType (https://github.com/TypeStrong/typedoc-default-themes/blob/master/src/default/partials/type.hbs)
Add links to other API pages: "Allows to update a column [[GridColDef]] model."
Filter out properties with "@ignore - do not document"
Prettify generated pages
Assert in CircleCI that json files are up to date

dtassone · 2021-05-06T09:27:31Z

Nice 👍

A couple of points.

The GridApi is the aggregation of all the hooks therefore, when we reach the proper level of pluginability, this one will be sort of dynamic, and maybe hooks will have to register their api somehow.
Therefore, maybe we should consider splitting the page in api sections, such as

GridCoreApi
....
GridRowApi
...

The events page is a great addition, however I believe it misses a bit of context. My idea was to put this page in a parent Advanced page.
this page would have the following section/sub pages depending on the length

Advanced
 - How the grid works? (the pattern...)
 - ApiRef (How to use it...)
 - Events (What you have done)
 - Components (how to create component, using useGridState...)

For the events page, I would add a warning or disclaimer to say something like Please note that you have to return the subscription in useEffect for it to be disposed correclty when the component unmount
Maybe a comment in the demo?

React.useEffect(() => {
// Please note that you have to return the subscription in useEffect for it to be disposed correclty when the component unmount
   return apiRef.current.subscribeEvent('columnResize', (params) => {...}, []
}

m4theushw · 2021-05-06T14:18:40Z

The GridApi is the aggregation of all the hooks therefore, when we reach the proper level of pluginability, this one will be sort of dynamic, and maybe hooks will have to register their api somehow.

I would leave the GridApi page with all the methods it has. This interface is what users will get when they call apiRef.current.

Your idea of splitting the API into sections is nice, since we have a lot of methods. But I would rather not create a page for them but generate a JSON that, with a custom component, we can embed it into the markdown docs. On each feature page (sorting, filtering, pagination, selection) we could have a section like "Controlling this feature programmatically" with the methods available (https://material-ui.com/components/data-grid/sorting/#apiref).

The events page is a great addition, however I believe it misses a bit of context. My idea was to put this page in a parent Advanced page.

An "Advanced Use" page is good, but I would prefer to do it in another PR. For now, we could move the catalog of events to https://deploy-preview-1529--material-ui-x.netlify.app/api/data-grid/. What do you think?

dtassone · 2021-05-07T10:59:14Z

For the apiPage I was talking about sections not separate pages.

An "Advanced Use" page is good, but I would prefer to do it in another PR. For now, we could move the catalog of events to https://deploy-preview-1529--material-ui-x.netlify.app/api/data-grid/. What do you think?

I think we can leave the events page as it is for now. Then open a new PR to add some more context or start the advanced page.

Issue on https://deploy-preview-1529--material-ui-x.netlify.app/api/x-grid/ => broken links around the doc

Also not sure about the menu.

Is it possible to show the api reference page as a landing page when you click the header?

oliviertassinari

Look like we are a long way done. 👍 for the hybrid approach taken, half automation looks great

docs/pages/api-docs/data-grid/index.md

package.json

docs/pages/api-docs/data-grid/grid-api.md

oliviertassinari · 2021-05-08T13:45:41Z

docs/src/pages/components/data-grid/events/events.md

+## Catalog of events
+
+{{"demo": "pages/components/data-grid/events/CatalogOfEvents.js", "bg": "inline", "hideToolbar": true}}


We would need to explain the upper-case import conversion logic.

oliviertassinari · 2021-05-08T13:47:33Z

docs/src/pages/components/data-grid/events/events.md

+) => () => void;
+```
+
+{{"demo": "pages/components/data-grid/events/SubscribeToEvents.js", "bg": "inline", "defaultCodeOpen": false}}


Was the plan to use GRID_COLUMN_RESIZE in the demos or columnResize? I can't remember.

We had this discussion in #1299 (comment). The plan was to use columnResize in demos and markdown. GRID_COLUMN_RESIZE could be documented, but users wouldn't be encouraged to use.

Ok, cc @mui-org/x to make sure we all agree on the approach. I personally don't really mind.

The advantage of GRID_COLUMN_RESIZE is IMHO to be easier to search, but since apiRef.current.subscribe is easy to grep in a codebase, I don't see it really important.

docs/src/pages/components/data-grid/events/events.md

docs/pages/api-docs/data-grid/grid-api.md

oliviertassinari · 2021-05-08T13:58:20Z

docs/scripts/buildApi.ts

+import path from 'path';
+import kebabCase from 'lodash/kebabCase';
+import * as prettier from 'prettier';
+import { renderInline as renderMarkdownInline } from '../../node_modules/@material-ui/monorepo/docs/src/modules/utils/parseMarkdown';


This could work

Suggested change

import { renderInline as renderMarkdownInline } from '../../node_modules/@material-ui/monorepo/docs/src/modules/utils/parseMarkdown';

import { renderInline as renderMarkdownInline } from '@material-ui/monorepo/docs/src/modules/utils/parseMarkdown';

The renderInline is only available in the next branch, but the monorepo used by the docs points to the master branch. That's why I'm importing it from the node_modules of the root directory.

oliviertassinari · 2021-05-08T14:04:27Z

Also, before we publish these pages live, it would be awesome to review in detail what we document, adding @ignore anything that looks suspicious in the docs. Basically, I think that we should default to no documentation, so we can asset it afterward if it's really valuable (the stronger the constraints, the impose, the more room for implementing features we have).

m4theushw · 2021-05-26T16:23:44Z

What is left in this one? Can we merge it and improve it at a later stage?
As always it won't be perfect at the first shot, but it needs to be in so we can improve it

@dtassone What was missing is the descriptions of events and methods, but that is already fixed and merged (#1572 and #1767). I think we can push forward and #1529 (comment) can be done in another PR.

docs/package.json

docs/src/pages/components/data-grid/columns/columns.md

packages/grid/_modules_/grid/models/api/gridCoreApi.ts

docs/pages/api-docs/data-grid/index.md

oliviertassinari · 2021-06-02T22:59:27Z

docs/scripts/buildApi.js

-/* eslint-disable */
-import * as babel from '@babel/core';


I'm pretty sure we will add this one back in the future for DataGrid, XGrid, GridToolbarExport, TreeView, etc. We are not here yet.

m4theushw force-pushed the generate-docs branch 3 times, most recently from bbd65da to 762789f Compare May 6, 2021 01:55

m4theushw marked this pull request as ready for review May 6, 2021 02:24

dtassone mentioned this pull request May 7, 2021

[docs] Explore typedocs #1212

Closed

oliviertassinari added the docs Improvements or additions to the documentation label May 8, 2021

oliviertassinari reviewed May 8, 2021

View reviewed changes

oliviertassinari mentioned this pull request May 8, 2021

[docs] Fix errors in the docs #1585

Merged

m4theushw mentioned this pull request May 10, 2021

Bump react-docgen from 5.3.1 to 5.4.0 #1594

Closed

m4theushw added 17 commits May 10, 2021 15:13

add description for all events

96233ea

update constant value

eb92e48

typos

7e7453c

first implementation of the docs generator

4fe7c21

wip

083fd67

cleanup

b643312

prettier

09b2fad

generate GridColDef

9e20f5b

throw error if reflection was not found

fbacfce

generate more pages

a7281e1

add support for literal types

0927892

parse links in the interface description

365d9db

escape description

e42508a

filter out properties with @ignore

ca5570e

add helper to render indexedAccess

a1935c4

generate events file

d0b3ecd

add events page

cedd400

m4theushw added 2 commits May 26, 2021 13:13

fix exports

a5102cb

generate docs

9d24bd0

oliviertassinari reviewed May 26, 2021

View reviewed changes

docs/package.json Outdated Show resolved Hide resolved

m4theushw added 4 commits May 27, 2021 18:17

Merge branch 'master' into generate-docs

1fdd8bf

hide descriptions on mobile

73d2132

add missing default values

1af0e1b

updates pages

e41721b

m4theushw mentioned this pull request May 27, 2021

[docs] Prepare for data grid auto-generated docs mui/material-ui#26477

Merged

1 task

m4theushw added 4 commits May 28, 2021 15:25

fix links in the API section

1900783

Merge branch 'master' into generate-docs

be91ef9

update monorepo

0608ace

generate docs

9bf4c92

m4theushw requested review from dtassone, DanailH and oliviertassinari June 1, 2021 12:00

oliviertassinari reviewed Jun 1, 2021

View reviewed changes

docs/src/pages/components/data-grid/columns/columns.md Outdated Show resolved Hide resolved

packages/grid/_modules_/grid/models/api/gridCoreApi.ts Outdated Show resolved Hide resolved

docs/pages/api-docs/data-grid/index.md Outdated Show resolved Hide resolved

m4theushw added 4 commits June 1, 2021 09:53

remove conflict comment

5c3b2fe

add slash at end of urls

1a68240

generate api with slash at the end of urls

edfbf87

formatting

074076a

m4theushw requested a review from oliviertassinari June 1, 2021 13:14

oliviertassinari approved these changes Jun 2, 2021

View reviewed changes

oliviertassinari reviewed Jun 2, 2021

View reviewed changes

m4theushw merged commit 0fd56fd into mui:master Jun 3, 2021

m4theushw deleted the generate-docs branch June 3, 2021 17:27

oliviertassinari mentioned this pull request Jun 3, 2021

[docs] Follow-up on docs generation #1826

Open

12 tasks

oliviertassinari mentioned this pull request Jul 21, 2021

[docs] Generate api doc for the GridExportCSVOptions interface #2102

Merged

m4theushw mentioned this pull request Oct 28, 2021

[DataGrid] Allow valueOptions to accept a function #2850

Merged

m4theushw mentioned this pull request Dec 8, 2021

[docs] Stop using typedoc to generate the API documentation #3320

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[docs] Automatically generate API docs #1529

[docs] Automatically generate API docs #1529

m4theushw commented Apr 30, 2021 •

edited

Loading

dtassone commented May 6, 2021

m4theushw commented May 6, 2021

dtassone commented May 7, 2021

oliviertassinari left a comment •

edited

Loading

oliviertassinari May 8, 2021

oliviertassinari May 8, 2021

m4theushw May 10, 2021

oliviertassinari May 10, 2021

oliviertassinari May 8, 2021

m4theushw May 10, 2021 •

edited

Loading

oliviertassinari commented May 8, 2021 •

edited

Loading

m4theushw commented May 26, 2021

oliviertassinari Jun 2, 2021

		## Catalog of events

		{{"demo": "pages/components/data-grid/events/CatalogOfEvents.js", "bg": "inline", "hideToolbar": true}}

	import { renderInline as renderMarkdownInline } from '../../node_modules/@material-ui/monorepo/docs/src/modules/utils/parseMarkdown';
	import { renderInline as renderMarkdownInline } from '@material-ui/monorepo/docs/src/modules/utils/parseMarkdown';

[docs] Automatically generate API docs #1529

[docs] Automatically generate API docs #1529

Conversation

m4theushw commented Apr 30, 2021 • edited Loading

Summary of changes

dtassone commented May 6, 2021

m4theushw commented May 6, 2021

dtassone commented May 7, 2021

oliviertassinari left a comment • edited Loading

Choose a reason for hiding this comment

oliviertassinari May 8, 2021

Choose a reason for hiding this comment

oliviertassinari May 8, 2021

Choose a reason for hiding this comment

m4theushw May 10, 2021

Choose a reason for hiding this comment

oliviertassinari May 10, 2021

Choose a reason for hiding this comment

oliviertassinari May 8, 2021

Choose a reason for hiding this comment

m4theushw May 10, 2021 • edited Loading

Choose a reason for hiding this comment

oliviertassinari commented May 8, 2021 • edited Loading

m4theushw commented May 26, 2021

oliviertassinari Jun 2, 2021

Choose a reason for hiding this comment

m4theushw commented Apr 30, 2021 •

edited

Loading

oliviertassinari left a comment •

edited

Loading

m4theushw May 10, 2021 •

edited

Loading

oliviertassinari commented May 8, 2021 •

edited

Loading