[RFC] Toolpad component documentation

[Janpot]

What's the problem? 🤔

As per last weekly meeting, there is insufficient documentation around working with Toolpad components.

What are the requirements? ❓

• There should be detailed documentation about each of the available, bindable, properties
• There should be guidelines and examples on the most common scenarios for each of the Toolpad components

What are our options? 💡

1. writing docs
2. not writing docs

Proposed solution 🟢

We add a section "Components" with one page per Toolpad component, either after the "Building UI" section, or inside it. Each of the pages could be structured as:

• title: the component name
• short description: the same as the component helper text.
• optional long description: providing more context to the former, but that would contain too much content suitable for the in-app helper texts
• API:
  • a list of properties, datatype, helper text of the property as per component definition, could be similatr to https://mui.com/x/api/data-grid/data-grid/#component-name
• optional use cases: a few recipes that show common scenarios this component could be sued in. e.g. shows how to bind something to the value of a text field, or how to run some code on a button click

Notes:

• When applicable, we should also include links to the MUI core/X docs for the same component.
• For components that don't have a counterpart in MUI core/X, perhaps we can link to a feature request?
• Should we invest time into extracting the helper texts from the component library, as a way of helping to keep them in sync with the docs? Any ideas on how could this be done?
• Is there a way to detect a change to the components (e.g. new component) and lint the docs to check whether it contains a corresponding page?

Resources and benchmarks 🔗

• MUI docs API page: https://mui.com/x/api/data-grid/data-grid/#props

[bytasv]

I'd also add 3rd option - generating docs - I feel that manually maintaining those docs might be error prone, especially once we have more and more components, so maybe it's worth to consider how much of that could be automated. If not fully, then maybe some partial automation which would require final touch ups done by engineers

[apedroferreira]

For sure the API section with the props description should be automated at least, directly from the component argTypes. Other than that we should always be able to add more information manually of course. The "template" proposed in this RFC sounds great to me!
The "long description" could maybe be more like a short "How to use it" guide.

Should we invest time into extracting the helper texts from the component library, as a way of helping to keep them in sync with the docs? Any ideas on how could this be done?

Could we make the argTypes importable from the toolpad-components package and then be able to use them however wanted?

Is there a way to detect a change to the components (e.g. new component) and lint the docs to check whether it contains a corresponding page?

I can't think of a super straightforward way to do this right now, but it could probably be done with a script by using git CLI commands.

[bytasv]

Should we invest time into extracting the helper texts from the component library, as a way of helping to keep them in sync with the docs? Any ideas on how could this be done?

should be possible with tsdoc parsers or something similar, I remmember in one of previous companies we did something similar to automatically generate component docs. Now that I wrote it, wondering if core team doesn't generate props from TS types too? 🤔 maybe we could just pick their method

Is there a way to detect a change to the components (e.g. new component) and lint the docs to check whether it contains a corresponding page?

One way that we could try to do something similar is by using playwright tests 🤔 we could i.e. build examples, that are executable, and then we could additionally executed examples in playwright. If they break, then we at least are aware

[Janpot]

should be possible with tsdoc parsers or something similar, I remmember in one of previous companies we did something similar to automatically generate component docs. Now that I wrote it, wondering if core team doesn't generate props from TS types too? 🤔 maybe we could just pick their method

The helpertexts in Toolpad are embedded as properties of an object on a hidden property of the component. This is different from core where they extract comments that are attached to types. They can use a typescript parser, detect what are exported components and read the related type information. For us it will probably have to be different. We could probably start by just importing the components directly, reading the hidden property, and access the argtypes directly. We probably don't have to statically analyze the components at all to get these helperTexts out.

[bytasv]

Ah, ok, I missunderstood. I thought you wanna extract helpers text from MUI docs so we don't have to manually keep it in sync.. nvm ignore then

[Janpot]

yes, that's what I mean, I just don't believe we will be able to reuse Core infrastructure

[prakhargupta1]

We have covered the API part of this discussion in our docs: https://mui.com/toolpad/reference/components/
Keeping it open for the other fields proposed in the component structure.