[docs] API reference layout overflow

[c3-joshsi]

Duplicates

• I have searched the existing issues

Latest version

• I have tested the latest version

Current behavior 😯

Because of the layout/styling of pages in MUI docs, when there is overflow content, it's annoying to have to scroll to read when there is so much empty space.

Screen.Recording.2022-08-26.at.2.06.34.PM.mov

Expected behavior 🤔

I shouldn't have to scroll if the dimensions of my browser are large enough

Steps to reproduce 🕹

Steps:

1. Go to https://mui.com/x/api/data-grid/data-grid-pro/#props (same with most other pages, cross projects).
2. Resize window, look at Props documentation

Context 🔦

Trying to read the docs

Your environment 🌎

npx @mui/envinfo

  Don't forget to mention which browser you used.
  Output from `npx @mui/envinfo` goes here.

Benchmarks

• Each prop with a long description: https://js.devexpress.com/Documentation/ApiReference/UI_Components/dxDataGrid/Configuration/#onEditCanceling and a demo or a link to a demo. Comment: It feels too much like a guide at the level of a prop, which doesn't make sense. However, the links to demo could be great:

• Using https://typedoc.org/ - https://youtu.be/Y07edRJd5QM?t=407. Comment: Cagatay is unsecured about this move, see his body language. So typedoc is probably not a good option. MUI X started to use its API and then moved one level lower as it was mostly bloat.

[siriwatknp]

@oliviertassinari Currently, the section has max-width of 105ch, should it increase for widescreen monitor?

[oliviertassinari]

the section has max-width of 105ch, should it increase for widescreen monitor?

@siriwatknp I think that we should be careful about the max width. As far as I know, the value of a small max width is to limits the amount of horizontal distance the eye has to travel before it has to go to the next line. The longer the distance is, the more likely our eye will land on the wrong next line. It's why the blog post area has a smaller max width than the docs, it's mostly content.

So if we increase the max width here, I think that it will improve the experience for the API tables, that are often on the API pages, but make it worse for the rest of the docs. Maybe only increasing the max-width on the API pages would make sense, but it would still be an issue for people like me that don't have an external monitor and API tables outside of the API pages. I think that the above proposal could solve this without the need to change the max width.

Previous attempts at problem: #30713 and #29062

---

I would propose a solution in this direction: #31745 (comment), an extract:

It would look like this:

https://mui.com/material-ui/api/button/#props

https://mui.com/x/api/date-pickers/calendar-picker/#props

[oliviertassinari]

There are also discussions about this problem in https://www.figma.com/file/MfirV6NOFAp2xxAZX1QU1V/Documentation?type=design&node-id=1475-18203&t=knHF31Rj2y4fLvgB-0.

[oliviertassinari]

The latest shape of the proposed solution on this:

It would solve #36544 too.

[samuelcolburn]

Link to my feedback on this issue in a similar thread.