[docs] Follow-up on docs generation

[oliviertassinari]

1529 is a major step forward toward exhaustive documentation of the API. These are opportunities I have seen that we could tackle next:

• [ ] 1. The new Events documentation page is limited. Frustration: https://github.com/mui-org/material-ui-x/issues/2001#issuecomment-872292432
  • Events are not specific to the Pro plan. Developers can listen to them with regular props: https://codesandbox.io/s/material-demo-forked-2lp71?file=/demo.js. We can add a new second about it.
  • Events can be imported as constants, there is no mention of it
  • "Fired when the grid is unmounted." Is this event really relevant?
• [ ] 2. The details of GridColDef seems hard to find. In the h2 Column definitions, we could have a h3 about the GridColDef API.
• [x] 3. The apiRef blocks miss the href in https://github.com/mui-org/material-ui-x/blob/0fd56fd31047707700317f14bebec7fb2bf4c37a/docs/src/pages/components/data-grid/filtering/filtering.md#L161
• [ ] 4. The apiRef blocks can be improved on how the new component pattern displays the information. It's a follow-up on https://github.com/mui-org/material-ui-x/pull/1529#discussion_r639248789. It seems that we have the following opportunities. We can improve the density of information, there is a lot of wasted space. We can reduce the number of clicks to access the information.
• [ ] 5. The apiRef blocks break the copy & paste the method name in https://material-ui.com/components/data-grid/filtering/#apiref

https://user-images.githubusercontent.com/3165635/126902292-76eef161-cfac-454b-933b-4480dbaec30f.mp4

• [ ] 6. The apiRef blocks pattern can be used in many other parts: density, edit row, csv export, and in the core too.

• [x] 7. We have a JSON docs generator in the core repository for React components (not interfaces). We should be able to use it for DataGrid, XGrid, GridToolbarContainer, GridToolbarExport, etc.

• [ ] 8. Once we have this JSON generated. We can move to the next step, read it to render the API page. We have a page component to read it in the core repository, we should be able to use it too.

• [ ] 9. The documentation of the interface in the core repository needs to be improved. A couple of examples: 1, 2, 3. It's not great, having no documentation for the headless component, it does not work. We have started to build a tool to solve this pain in this repository. We need the same one in the core repository. For instance:

  • We could share the JSON generator. It wouldn't make sense to duplicate fixes like #2003.
  • We could share the JSON rendering logic, so when we improve https://github.com/mui-org/material-ui-x/pull/1529#discussion_r639248789, it benefits the whole set of components.

• [ ] 10. We have two opportunities to better link GridExportCsvOptions that we don't leverage:

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

• [ ] 11. In some cases, it might feel overkill to create a dedicated page for small interfaces. Or maybe we should have the two but when it's simple enough, also embed in the docs page, as @m4theushw did for the apiRef. applyFilter is listed twice https://material-ui.com/components/data-grid/filtering/#apiref

• [ ] 12. We miss more details about the apiRef, we could:

  • remove this URL /components/data-grid/events/
  • move content of the event page inside a /components/data-grid/advanced/ URL, under a h2 (not a h1 as currently)
  • add a description about how apiRef works (h2)
  • link the sub section of apiRef to the relevant features, e.g. filtering

  For instance, it could look like this:

  # Data Grid - Advanced
  
  ## apiRef
  
  Introduction, how to use it.
  
  ### Features
  
  - Filtering: https://master--material-ui-x.netlify.app/components/data-grid/filtering/#apiref
  - Export
  - etc.
  
  ## Events
  
  Introduction, the naming convention
  
  ### Props
  
  ### subscribeEvent
  
  apiRef
  
  ### Catalog of events

  Feedback on it here: https://github.com/mui-org/material-ui-x/issues/1826#issuecomment-854620221

cc @m4theushw

[dtassone]

As mention before I think we can create an advanced page, with events and other more advanced concept in it, like apiRef...

[oliviertassinari]

I think we can create an advanced page, with events and other more advanced concept in it, like apiRef.

@dtassone Could you expand? Do you mean that you would?

• remove this URL /components/data-grid/events/
• move content of the event page inside a /components/data-grid/advanced/ URL, under a h2 (not a h1 as currently)
• add a description about how apiRef works (h2)
• link the sub section of apiRef to the relevant features, e.g. filtering

Something like this:

# Data Grid - Advanced

## apiRef

Introduction, how to use it.

### Features

- Filtering: https://master--material-ui-x.netlify.app/components/data-grid/filtering/#apiref
- Export
- etc.

## Events

Introduction, naming convention

### Props

### subscribeEvent

apiRef

### Catalog of events

Sounds good

[dtassone]

Yes something like that seems great. It would allow more advanced users to find deeper use cases of the grid in one place and to understand in more depth the concepts. So we could add links to the advanced page in different pages such as rows streaming...