Support for autosummary-style output with each method/property on a separate page

[tswast]

See internal issue b/401261155

Is your feature request related to a problem? Please describe.

For the bigframes docs, especially the pandas-related APIs in bigframes such a DataFrame, the number of methods on the same page is much too many. Just scrolling the table of contents for subheadings (properties/methods) takes multiple screen lengths.

The also makes SEO difficult. Even when Google finds the correct page (e.g. a search for "bigframes dataframe explode" contrast with a search for "pandas dataframe explode"), it doesn't usually include the header and even when it does it might not take you to the right spot because of how long it takes for the page to fully render.

Describe the solution you'd like

When I use autosummary to create a separate page per method, respect that choice and create a separate yml per method / page in the normal sphinx docs.

Describe alternatives you've considered

Could add some "autosummary" like option to generate a yml for each attribute for the whole package.

Could move away from docfx yaml and instead have sphinx generated pages hosted directly.

Additional context

General handwritten improvements: #156

PR to move to autosummary in bigframes: googleapis/python-bigquery-dataframes#1473

[dandhlee]

This is feasible, but it will create a lot of pages which may or may not affect load time performance for folks on c.g.c/python/docs/reference/bigframe as it tries to load, possibly, 5k+ entries. It shouldn't be that bad as we've only noticed this issue in other languages that had fully fleshed out entries for all libraries (~50k+ entries), but it may eventually get there or start to show noticeable performance issues.

I suppose we could support it just for specified classes, but that might create a confusing experience as only some methods show up on the left-nav.

[tswast]

c.g.c/python/docs/reference/bigframe as it tries to load, possibly, 5k+ entries.

One thing pandas does is only expand the entry for a class in the TOC once you've dropped down into some function in that class. For example, the TOC here shows all the entries for Series, but DataFrame is not expandable until you go to the DataFrame page.

With some additional folder structure, I think that nested toc files would be feasible, but I'm not sure what complications that would cause for the plugin and/or docs pipeline.

That said, I don't think we'd have to solve that for bigframes right now, though it will be quite a large toc.

[dandhlee]

Hmm I'm actually not entirely sure if that's feasible with various TOC structures (how do we only show / hide certain items depending on where we click?)

Otherwise we'd have to control this with the book, or just rely heavily on the collapsable sections. I could look into this in a few months if desired by the team as an option.