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] Subdivide and reorganize navigation bar #15014

Merged
merged 16 commits into from
Nov 5, 2024

Conversation

samuelsycamore
Copy link
Contributor

@samuelsycamore samuelsycamore commented Oct 18, 2024

The primary purpose of this PR is to better organize the Data Grid navigation, which has outgrown its current structure, by introducing new subheaders and applying them consistently across all of the X products. This should help the docs scale comfortably over the next couple years.

  • "Common features" –> "Core Main features"
  • consistent placement of docs repeated across packages
    • API references live in Resources sections
    • Accessibility docs live in Main features
    • FAQs live in Getting Started sequence (following Material UI's pattern)
  • "Common concepts—Custom subcomponents" –> "Common concepts—Slots and subcomponents" to differentiate the doc from the individual product "Custom subcomponents" page - I'd like to return to these pages another time, but for now this is just a change to the nav bar and some links.

I don't have strong opinions about the order of most of the pages under the subheaders, so if others feel strongly about rearranging any of them please speak up!

Data Grid

  • (Getting started sequence)
  • Main features
  • Advanced features
  • Customization
  • Resources

Date and Time Pickers

  • (Getting started sequence)
  • Components
  • Main features
  • Localization
  • Customization
  • Resources

Charts

  • (Getting started sequence)
  • Components
  • Main features
  • Resources
  • Future components - I think this section should be merged into Components after one or two more Charts move from "Planned" to "Preview"

Tree View

  • (Getting started sequence)
  • Simple Tree View
  • Rich Tree View
  • Main features
  • Resources

@samuelsycamore samuelsycamore added the docs Improvements or additions to the documentation label Oct 18, 2024
docs/data/pages.ts Outdated Show resolved Hide resolved
Copy link
Member

@flaviendelangle flaviendelangle left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Approving the pickers and tree view changes 👍

Copy link

This pull request has conflicts, please resolve those before we can evaluate the pull request.

@github-actions github-actions bot added the PR: out-of-date The pull request has merge conflicts and can't be merged label Oct 29, 2024
@github-actions github-actions bot removed the PR: out-of-date The pull request has merge conflicts and can't be merged label Oct 29, 2024
@samuelsycamore samuelsycamore marked this pull request as ready for review October 29, 2024 22:24
docs/data/pages.ts Outdated Show resolved Hide resolved
docs/data/pages.ts Outdated Show resolved Hide resolved
docs/data/pages.ts Outdated Show resolved Hide resolved
docs/data/pages.ts Outdated Show resolved Hide resolved
docs/data/pages.ts Outdated Show resolved Hide resolved
Copy link
Member

@LukasTy LukasTy left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nice unification, thank you for taking care of it. 👍
Data Grid sees the biggest overhaul. 🎉
If the existing raised points are addressed, everything else looks good. 💯

docs/data/pages.ts Outdated Show resolved Hide resolved
docs/data/pages.ts Outdated Show resolved Hide resolved
docs/data/pages.ts Outdated Show resolved Hide resolved
docs/data/pages.ts Outdated Show resolved Hide resolved
@samuelsycamore
Copy link
Contributor Author

samuelsycamore commented Nov 1, 2024

I just realized that the Data Grid's Recipes section has pages for Editing and Row Grouping—but other features like Filtering and Rows have a Recipes page alongside their main content, rather than in this section. I think it should be one way or the other for all features. Which do you prefer @cherniavskii @LukasTy @KenanYusuf : All recipe docs in the dedicated Recipes section, or living alongside their main feature docs? (I would propose moving them all to the dedicated Recipes section, but I don't have a strong preference on this.)

@cherniavskii
Copy link
Member

All recipe docs in the dedicated Recipes section, or living alongside their main feature docs?

I think the plan was to have recipes alongside their main feature docs. I moved editing recipes to the Editing section in #7772, but I never finished that effort 🫠
I propose doing this:

  • Editing
    • Overview
    • Recipes
  • Row grouping
    • Overview
    • Recipes

There should be no changes to the pages URLs required for this.

@LukasTy
Copy link
Member

LukasTy commented Nov 4, 2024

All recipe docs in the dedicated Recipes section, or living alongside their main feature docs?

I think "Recipes" is mostly relevant to the Data Grid.
For other packages we don't have such a clear notion, maybe Charts could replace "Demos" with "Recipes".
cc @mui/xcharts

Whereas, for Pickers, it is pretty rare to have many examples, we mostly showcase props and customization options.

@flaviendelangle
Copy link
Member

Whereas, for Pickers, it is pretty rare to have many examples, we mostly showcase props and customization options.

The closest we have from a recipe are the examples in "Custom field" and they should remain in a customization-related page, not a page called "Recipe" IMHO.

So I'm fine with the grid moving their recipes next to the feature.

@samuelsycamore
Copy link
Contributor Author

Tangential: "Recipes" as a concept does seem to be unique to the Data Grid. We don't have them in play for any of the other MUI products. Some Material UI and Joy UI components have "Common Examples" intended to be closest to real-world UI in the demos, but maybe that's a slightly different concept. I don't think the Charts "Demos" would fall into the Recipes category either, because it seems like recipes are more about complex use cases that implement advanced features. (From what I've seen, the question of whether or not a demo could be considered a recipe might be, "could I create a full tutorial around this implementation?") If users find the Data Grid recipes helpful then we should consider creating them for other packages/components as well.

For now, I'll move forward with @cherniavskii 's proposal for these pages and then I think this PR will be ready to merge. Thanks for the input everyone!

@samuelsycamore samuelsycamore merged commit a377084 into mui:master Nov 5, 2024
18 checks passed
Comment on lines +396 to +406
{
pathname: '/x/api/picker-resources',
subheader: 'Resources',
children: [
{
pathname: '/x/api/date-pickers-group',
title: 'API reference',
children: [{ pathname: '/x/api/date-pickers', title: 'Index' }, ...pickersComponentApi],
},
],
},
Copy link
Member

@oliviertassinari oliviertassinari Nov 23, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This lead to two bugs. Fixing this in mui/material-ui#44514.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
docs Improvements or additions to the documentation
Projects
None yet
Development

Successfully merging this pull request may close these issues.

7 participants