docs: API description column & comprehensive TOC

[eesayas]

Description

This is an initial step in redesigning our documentation site, focusing on improving the API pages by reintroducing the description column and a more comprehensive TOC.

Markup:

N/A

[MajesticPotatoe]

Some things to note:

• some prop/slot/event hrefs have special characters (that should be cleaned up) that dont match their TOC counterpart (eg [`item.${string}`] points to #slots-[`header.{string}`] and should point to #slots-header-string like the toc item
• would prefer reflowing table content over scrolling-y. Some api tables are really long and you can descriptions get cut off in some breakpoints
• mobile support lacking

Would suggest using v-data-table api as a good example to work with as its probably one of the more complex and heftier api pages with dynamic/funky strings lots of content to fit in.

[eesayas]

@MajesticPotatoe I was thinking of having a follow up PR to utilize v-data-table for mobile support. I know in Vuetify 2 data-table becomes a card which doesn't seem to happen on v3 yet.

Perhaps I should have a next-docs branch to merge to. I'm anticipating making multiple follow up PRs.

[eesayas]

@MajesticPotatoe irt the table content. I was thinking of implementing different views for API content. For example: https://mui.com/material-ui/api/button/ has table and list view mode. Putting it back to tables is a first step to that.

The thing is should api descriptions be that long? Once we do the auditing I think descriptions should be concise and should point to an example in components page as needed.

I'm open to keeping the description as it's own row. But maybe improving the ui with a space in between items https://v15.vuetifyjs.com/en/components/menus/.

[MajesticPotatoe]

Not sure a next-docs is really necessary. Could just make this branch/PR the comprehensive "api overhaul" and then just PR's that are meant to merge into this one.

Correct, descriptions should be concise and to the point. Lengthy ones might want to be cleaned up and then the more in depth explanation moved to a relevant doc page/example and then linked in the description.

Different view might be cool, can hook it up as a user setting.

Mobile support should be rather easy, hook up display composable to ApiTable, and then just add alternative row styling on breakpoint.
TOC should be easy fix by removing any non-alpha characters except hyphens (there might be a utility function used somewhere that does that)

[johnleider]

This looks really good. Only issue revolves around the TOC. Going between different types of pages, it sometimes gets hung up and doesn't update.

[johnleider]

should this only be removed for API pages? we don't want to remove it for the entire docs

[KaelWD]

"redesign" more like return to monke

There's a reason this was changed, it's pretty awful on narrow windows or with long types.

[johnleider]

Can we make it configurable and potentially offer some different options? I don't know if this rewrite is the answer, but I do know the current way of viewing the API feels cumbersome to me.