[docs-infra] Allow to browse props in the table of content

[adevick]

Duplicates

• I have searched the existing issues

Related page

https://mui.com/x/api/data-grid/data-grid-pro/

Kind of issue

Missing information

Issue description

I am trying to read the docs but the UI is too skinny and I have to side scroll then sometimes when side-scrolling it will default to going back to a page in the browser. It would be nice to be able to read the docs clearly with more space.

Context 🔦

Trying to search and read the docs for data grid pro.

[alexfauquette]

There is an ongoing effort on this topic. The preview can be seen here:

https://deploy-preview-9187--material-ui-x.netlify.app/x/api/data-grid/data-grid-pro/

[samuelcolburn]

I don't know if this should be a separate issue or should be a comment on the current API draft @alexfauquette linked, but the sizing of this page affects basically all API pages with sufficiently detailed descriptions:

My personal suggestions are on the attached image, but I'll repeat them here:

• The documentation is being cut off despite large amounts of padding on larger screen sizes. It should be allowed to expand to the full space available and avoid being cut off wherever possible.
• On smaller screen sizes, the contents right-side menu takes up unnecessary space, and should be a togglable nav drawer like the root navigation to maximize readable space.
• I personally do not prefer the draft proposals layout compared to the current layout, however it does solve the readability issue. Perhaps stacking type/default columns into a single column, along with optimizing/reducing unused space would be sufficient?

[alexfauquette]

I personally do not prefer the draft proposals layout compared to the current layout, however, it does solve the readability issue.

Do you have specific reasons, or is it just a feeling

Perhaps stacking type/default columns into a single column, along with optimizing/reducing unused space would be sufficient?

That does not work with our entire set of components. To resume most of our discussions and examples: some props have big descriptions (those with complex behavior) some other props have big typing (those with multiple options) and tables are not well suited to display data with that kind of variation. That's why we went to a list layout

[danilo-leal]

Nice, appreciate the suggestions here! Though I think that even if we widened the main content container to better fit each prop description and thus keep the table design, that would mean a much larger refactor on the docs architecture as well as still preserve some unbalanced whitespace.

It's a tough trade-off that we acknowledge, given the table layout does contain a good scalability level, whereas the list approach we're currently leaning towards has it weaker. However, the latter is much more scalable for different sets of components with diverse content!

[samuelcolburn]

Do you have specific reasons, or is it just a feeling

I think the only specific reason I could give is that it feels easier to scroll through a large alphabetical table of API options to find what you need compared to the list variant. I think this is especially true when you don't know exactly what you're looking for. For example, I think it's easier to review all the possible "onX" callback functions when looking at a table, compared to a list. Maybe if all the API options were listed in either the left or right navigation drawers that would solve it? Granted, I don't know how big of a refactor that would require.

Perhaps stacking type/default columns into a single column, along with optimizing/reducing unused space would be sufficient?

That does not work with our entire set of components. To resume most of our discussions and examples: some props have big descriptions (those with complex behavior) some other props have big typing (those with multiple options) and tables are not well suited to display data with that kind of variation. That's why we went to a list layout

I see your point, but I tried to quickly find an example of lengthy typing/default values that would fit your description and wasn't able to.

Though I think that even if we widened the main content container to better fit each prop description and thus keep the table design, that would mean a much larger refactor on the docs architecture as well as still preserve some unbalanced whitespace.

I can understand that. I think I would argue that whitespace throughout the docs could be trimmed significantly, but of course that's easy to suggest without looking at the scope of that suggestion in detail.

[alexfauquette]

Maybe if all the API options were listed in either the left or right navigation drawers that would solve it?

Now that items have a hash, it sounds doable, and interesting for further developpement

[oliviertassinari]

Now that items have a hash, it sounds doable, and interesting for further development

Example of docs that does this:

• https://ariakit.org/reference/use-combobox-store#optional-props
• https://typedoc.org/example/interfaces/EasyFormDialogProps.html#submitButtonClass

It sounds worth trying 👍

[avalatea]

I saw the new page, and it looks great on my screen! Not sure if it will be deployed to production eventually?

If we're still looking for options to keep the table, I think just having the ability to hide the menus on the left and right side of the screen will do wonders as well. :)

[danilo-leal]

@avalatea, hey! The API content design was recently revamped, and it's been live for a while now — check the production link here. It's not quite what was wireframed here, but it tackles the problem, providing different layouts to choose from!

[avalatea]

Ahh I see! Looks like I had to toggle it. Thank you @danilo-leal . Everything looks great.

[avalatea]

Is it also a high lift to do this for interface pages as well? Looks like there's only a feedback button.

[danilo-leal]

Good call — we should update this as well! cc @alexfauquette

[alexfauquette]

Yes, documentation for Grid interfaces are markdown pages generated by custom script of the X team. It will probably require some time to move them in a JSON format like other API pages

I would prefer not do that right now because those scripts are moving a lot: #11303