[docs-infra] Improve API page deprecation info

[DiegoAndai]

Summary

• Standardize API page warnings
• Add "DEPRECATED" label to props and class lists
• Add support for class deprecation

Details of each are below

Standardize API page alert

Introduce the ApiWarning component to standardize all API page warning alerts: deprecations and "needs to be able to hold a ref" alerts on both table and list views.

This doesn't include other warnings throughout the docs, which might be something we should look into but goes beyond the scope of this PR.

Add "DEPRECATED" label to props and class lists

This indicates deprecations when lists are collapsed. Without this change, deprecations cannot be seen until the prop is expanded.

Add support for class deprecation in API docs:

This is required, for example, for #40418. Here's an example of how it would look like.

Notes

This is my first docs-infra PR, so please correct anything I might not be aware of 😊.

[mui-bot]

Netlify deploy preview

https://deploy-preview-40440--material-ui.netlify.app/

Bundle size report

No bundle size changes (Toolpad)
No bundle size changes

Generated by 🚫 dangerJS against ebde672

[alexfauquette]

What about splitting the information "there is a deprecation" with isDeprecated in the json you're modifying, and saving the description of the deprecation in the translationFolder. The goal being to keep all stuff to translate in a single file

@michaldudak Could you confirm it's what you intended to do in your refacto of this script?

[siriwatknp]

Is it possible to add DEPRECATED label similar to STATE? This would make it easy to see when the content is not collapsed.

[michaldudak]

We need translated text in the translations JSON for sure.
Looking at this now, I think I unnecessarily added the description field to the classes array items (it should live just in translations, similarly to props), causing duplication.
Let's follow how the props work and have the translatable text in the translations directory, not in the main API definition JSON.

[michaldudak]

The implementation looks good.
One issue I found is when a state class is deprecated, the "deprecated" tag isn't shown on the list view, but the "state" tag is colored differently:

[DiegoAndai]

@alexfauquette @danilo-leal, this is ready for your re-review 😊 I updated the description with the added changes.

I didn't know how to figure out why the MUI X deprecation warnings in their API pages didn't update. I thought these were shared.

[alexfauquette]

I didn't know how to figure out why the MUI X deprecation warnings in their API pages didn't update. I thought these were shared.

Effectively the X docs is depending on the core one. So after merging this PR X will be able to update it's dependency to the monorepo and the get the update 👍

I made a try using your branch, but seems you don't have deprecated classes, nothing change

[alexfauquette]

Sound very nice. Especially having a single component for warnings 🙏

Could you update the #40418 to be able to see the components with their last version of the modification?

[DiegoAndai]

Could you update the #40418 to be able to see the components with their last version of the modification?

Done 😊: https://deploy-preview-40418--material-ui.netlify.app/material-ui/api/accordion-summary/#classes

@alexfauquette

[alexfauquette]

Amazing 🎉

[danilo-leal]

Looks awesome! 🤙