[docs] Prepare for data grid auto-generated docs #26477
Conversation
Details of bundle changes.Comparing: df22bc2...a7ffe08 Details of page changes
|
docs/src/pages.js
Outdated
| title: 'Data Grid', | ||
| children: [ | ||
| { pathname: '/api-docs/data-grid', title: 'API Reference' }, | ||
| { pathname: '/api-docs/data-grid/data-grid' }, |
There was a problem hiding this comment.
Are these pages expected to return 404 at the moment? https://deploy-preview-26477--material-ui.netlify.app/api/data-grid/data-grid/
There was a problem hiding this comment.
Yes, these pages are available in https://deploy-preview-1529--material-ui-x.netlify.app/api/data-grid/data-grid/.
| pathname: '/api-docs/data-grid', | ||
| title: 'Data Grid', | ||
| children: [ | ||
| { pathname: '/api-docs/data-grid', title: 'API Reference' }, |
There was a problem hiding this comment.
On the landing page it's a sub-item (https://deploy-preview-26477--material-ui.netlify.app/) but once you go to https://deploy-preview-26477--material-ui.netlify.app/api/data-grid/, the nested menu structure disappears.
There was a problem hiding this comment.
Because the redirect rule sends to https://master--material-ui-x.netlify.app/api/data-grid/. Once mui/mui-x#1529 is merged it will work.
There was a problem hiding this comment.
Thoughts:
- I assume we will also need to update the
nextbranch to prepare once we drop v4 support in the mui-x repo. - Do we even need to add the data grid API pages in the side nav?
- What would be the best way to get a sound documentation without the need to send two PRs in two repositories?
- Option 1. Change the docs structure to isolate the two "products" core vs. advanced. But what about the date picker that is split with the date range picker? But what about the navigation experience for the developers, would It still be fluid enough?
- Option 2. Have the two repository expose JSON structure that the docs fetches when it needs to render the nav
- Option 3?
@oliviertassinari Well, at least DataGrid and XGrid should be because they're components.
|
My underlying idea was to remove the existing side nav all together for the API. Instead, have one API "collection" page per package that list all the other pages (for each module). These API "collection" pages would be limited, like 5, and could be displayed in the side nav. For instance, one inside the data grid navigation, one inside the system navigation. The problem it would solve: 1. The API side nav is too long to be useful 2. It's unclear what each package expose as an API. I'm curious to hear thoughts on this proposal.
Agree for how the incentive to use a Button and a DatePicker is different. Splitting the date picker between two repositories doesn't seem practical. I mean, we very often apply the same change on all the components at once.
No, it would happen at build time. |
This idea of separating documentation between packages is what I had drafted.
|
|
@m4theushw We are going off-topic, but this is an interesting and important discussion. We will need to involve @danilo-leal. I think that we could continue in this direction but focus more on a segmentation per "use case". A possible structure:
A "realm" means more isolation from the rest of the documentation. I could find 4 classes of approach, summarized here:
|
|
@m4theushw I have cherry-picked the changes to HEAD, so we don't forget once we switch to v5 as the main domain: 17a841b. |
oliviertassinari
added
the
component: data grid
Preview: https://deploy-preview-26477--material-ui.netlify.app/api/css-baseline/
⚠WARNING⚠
Once merged this PR, sync with @mui-org/x before doing the push to the docs repo. This is to prevent dead links since existing pages were moved.
Related to mui/mui-x#1529
Preview https://deploy-preview-1529--material-ui-x.netlify.app/api/data-grid/data-grid/