Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[docs-infra] Display deprecation messages in API pages #42352

Merged

Conversation

aarongarciah
Copy link
Member

@aarongarciah aarongarciah commented May 23, 2024

Now that we're able to use JSDoc tags to annotate components and hooks (see #42327), we can use @deprecated JSDoc tags from components and hooks as the source of truth to automatically display deprecation alerts in API pages.

Changes included in this PR:

  • Add a new deprecated property in docs json files (e.g. docs/pages/material-ui/api/hidden.json)
  • Add a new deprecationInfo property in docs translation json files (e.g. docs/translations/api-docs/hidden/hidden.json)
  • Display an alert with the info coming from the json files. If the deprecationInfo field is empty, display a generic message.

ℹ️ Important: the changes work in API pages from Material, Joy, and System. The deprecation alert is not displayed in Base UI pages for now. I've pinged the Base UI to see if it's also worth applying the changes there.

Preview link: https://deploy-preview-42352--material-ui.netlify.app/material-ui/api/hidden/

image

@aarongarciah aarongarciah added the scope: docs-infra Specific to the docs-infra product label May 23, 2024
@aarongarciah aarongarciah changed the title [docs-infra] Display deprecation messages in components API pages [docs-infra] Display deprecation messages in API pages May 23, 2024
@mui-bot
Copy link

mui-bot commented May 23, 2024

Netlify deploy preview

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

Bundle size report

No bundle size changes (Toolpad)
No bundle size changes

Generated by 🚫 dangerJS against 6ac6530

@aarongarciah aarongarciah force-pushed the aarongarciah/docs-api-deprecation-messages branch 4 times, most recently from 2aff948 to e4253ba Compare May 24, 2024 09:11
@aarongarciah aarongarciah marked this pull request as ready for review May 24, 2024 09:13
@aarongarciah aarongarciah requested a review from a team May 24, 2024 09:18
@aarongarciah
Copy link
Member Author

@michaldudak is it worth applying the changes to Base UI docs? I'm not sure what the status of Base UI docs is so I don't want to spend time there if it's going to go away soon.

@michaldudak
Copy link
Member

The current Base UI docs will be replaced sometime in the future, so I don't think it's worth spending time on them now. The new Base UI docs can make use of it, but it's not urgent. We're not stable yet, so we don't think about deprecated APIs now :)

@aarongarciah aarongarciah changed the base branch from master to next May 27, 2024 11:56
@aarongarciah aarongarciah changed the base branch from next to master May 27, 2024 11:56
@aarongarciah aarongarciah changed the base branch from master to next May 27, 2024 12:11
@aarongarciah aarongarciah force-pushed the aarongarciah/docs-api-deprecation-messages branch from e4253ba to 0a9a789 Compare May 27, 2024 12:11
@aarongarciah
Copy link
Member Author

Updated the PR leveraging Danilo's Alerts standardization and switched the target branch to be next.

@aarongarciah aarongarciah merged commit b8a28e1 into mui:next May 27, 2024
22 checks passed
@aarongarciah aarongarciah deleted the aarongarciah/docs-api-deprecation-messages branch May 27, 2024 12:47
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
scope: docs-infra Specific to the docs-infra product
Projects
None yet
Development

Successfully merging this pull request may close these issues.

None yet

5 participants