[MuiThemeProvider] Document Nesting semantics

[BGehrels]

• This is not a v0.x issue.
• I have searched the issues of this repository and believe that this is not a duplicate.

Expected Behavior 🤔

When i open https://material-ui.com/customization/themes/#nesting-the-theme i would expect to know the resulting effective styles are when i write

const GlobalTheme = createMuiTheme({
  palette: {
    primary: {
      main: "#003B36"
    },
    secondary: {
      main: "#D76A03"
    }
  }
});

const LocalTheme = createMuiTheme({
  palette: {
    secondary: {
      main: "#ECA72C"
    }
  }
});

<MuiThemeProvider theme={GlobalTheme}>
    <MuiThemeProvider theme={LocalTheme}>
         <!-- what is the primary color here? -->
    </MuiThemeProvider>
</MuiThemeProvider>

Current Behavior 😯

All the docs tell you is: "The theming solution is very flexible, as you can nest multiple theme providers.". But it does not tell you what effects nesting has on your theme.

Examples 🌈

https://material-ui.com/customization/themes/#nesting-the-theme

Context 🔦

Without it being documented, i would have expected that the primary color in the example above wuold be "#003B36" - because i did not explicitly define a new one in the LocalTheme. While it is okay that the implemented behaviour is different, the actual behaviour should be documented.

Issues like #6129 and #12496 show, that there is a need for such documentation.

[eps1lon]

All the examples have the source code included which you can view in the docs.

As with every context it's always the nearest value. If you want to merge you can use the callback overload. We could add a sentence about using the callback to merge and add an example to the docs that shows that a primary color from a grandparent is ignored without a merge. I'm happy to review such a PR.

PS: One issue you linked was a feature request from over a year ago.