[docs] Automatically generate the documentation for the exported modules

• I have searched the issues of this repository and believe that this is not a duplicate.

Summary 💡

Make the API reference as comprehensive as possible.

The problem 🔦

The documentation is critical to the success of the product. This issue is an extension of mui-org/material-ui-x#1211, and probably even more important.

In the core repository, we have started to face this pain but didn't try to solve it properly yet. For the few modules we export that are not components, we manually maintain the API with a somewhat consistent markdown format. This includes hooks, custom functions. There isn't a lot. This manual generation of the documentation of the non-components is time-consuming, error-prone, and easy to get out of sync.

With the data grid, is currently hard to understand what API is available. I was looking into https://material-ui.com/components/data-grid/filtering/#custom-filter-operator and it took me a while to under the structure of the column definition filter operators. In the end, I had to get my hand dirty to create a codesandox to truly understand the structure of the API. I think that clear documentation of the types would have saved me time.

cc @mui-org/maintainers

Related issues

• mui-org/material-ui-x#446

A possible solution 🧩

One proposal for the solution (for the whole mui-org):

1. We replace the API navigation

with a page that links all the other pages. We can even structure the data, with headers per category. This would allow scaling to more modules. I think that we reached a point where there are simply too many links to have a side nav like this keep having sense.

2. We create an API extractor, to convert the types into a json structure the documentation can render. I made a POC in this direction on mui-org/material-ui-x#1212. It seems to work, it's fast. A preview.

3. We build a React component to render json data. It has to be fast. We might have a lot of information to render

4. We increase the coverage. The first possible tradeoff is to render the API only where appropriate. For instance, we could replace this manually authored markdown https://material-ui.com/components/app-bar/#usescrolltrigger-options-trigger with it. We could also include the description of GridFilterOperator on this page https://material-ui.com/components/data-grid/filtering/#custom-filter-operator. Now, if we move forward with 5, 4. might not be as relevant. We could link the other pages instead.

5. We consider documenting all the public API. In the POC with typedocs, mui-org/material-ui-x#1212, I didn't check that it only generates the types for the public modules. We would need to double-check. My main concern here is scalability. How much time does it take to build? How many new pages would Google need to crawl (there is a budget)? Maybe we should bypass React and our components here. Use plain old HTML + CSS.
   Regarding the URLs, since we try to have the whole codebase under the same namespace, we could keep /api/name-of-the-module.

Benchmark 👀

• https://www.telerik.com/kendo-react-ui/components/grid/api/
• https://lodash.com/docs/4.17.15#pickBy
• https://ag-grid.com/javascript-grid/grid-api/
• https://stripe.com/docs/js/payment_request/events
• https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/S3.html
• https://react-restart.github.io/hooks/api/useFocusManager
• https://react-select.com/props
• https://react-table.tanstack.com/docs/api/useColumnOrder (I have heard multiple times that the docs of react-table is far far from great).

Start by reviewing the proposed API extractor in mui-org/material-ui-x#1212 and the current API navigation described in this issue. Compare the proof of concept with the desired coverage, rendering, scalability, and URL requirements; completion would require an agreed implementation plan and generated API documentation for exported modules.