@Nodd Two comments:

1. One can achieve substructuring using regular sections with individual .. autosummary:: directives. This is maybe slightly less elegant than one table with separations, but does the job. You can see a result at https://matplotlib.org/stable/api/axes_api.html#plotting which is generated from https://github.com/matplotlib/matplotlib/blob/main/doc/api/axes_api.rst

2. Autosummary may currently lack in some parts, but fundamentally I believe that the missing features could be added. It may be worth to consider enhancing autosummary rather than tediously hard-coding hundreds of functions.

1. One can achieve substructuring using regular sections with individual .. autosummary:: directives. This is maybe slightly less elegant than one table with separations, but does the job. You can see a result at https://matplotlib.org/stable/api/axes_api.html#plotting which is generated from https://github.com/matplotlib/matplotlib/blob/main/doc/api/axes_api.rst

I tried to use multiple tables before (by hand) in #125809, but the result was not very good, especially for small tables. Maybe it's just a problem with the theme?

2. Autosummary may currently lack in some parts, but fundamentally I believe that the missing features could be added. It may be worth to consider enhancing autosummary rather than tediously hard-coding hundreds of functions.

To be honest, the documentation improvement was a way for me to start to contribute to CPython. As far as I can tell, the whole python documentation is already "hard coded", there is no link between the docstrings and the html pages. It allows to have a documentation dedicated to console use with the help command using the dosctrings without the RST formatting, and a html documentation with full formatting. Automated tools would mix the two worlds that are currently separated.

If the aim is to avoid hard coding functions to document the API, there are specialized tools, for example pydoctor that can interact with sphinx via intersphinx.

Maybe it's just a problem with the theme?

I think so. With minimal CSS tuning I can get:

To be honest, the documentation improvement was a way for me to start to contribute to CPython.

Documentation is indeed a great way to start contributing 👍.

As far as I can tell, the whole python documentation is already "hard coded".

There are pros and cons for hard-coding. Large parts of the Python documentation are older than (semi-)automated API documentation tooling. I don't know the Python documentation strategy, i.e. whether that's intentional or just the way it has always been. I want to encourage a discussion and conscious decision when embarking on larger scale changes to the docs. It may be the right approach to hard-code the summaries, but it should be weighted against other options. I also want to emphasize that tooling can be improved. "the current autosummary does not do x" is IMHO not sufficient to justify hard-coding. Since the summary tables are not only a large one-time effort but need continued synchronization, improving on automatization shoud at least be considered. Note also, that it doesn't have to be autosummary, one could e.g. also imagine creating a directive that generates a summary table from the function definitions below.

Maybe it's just a problem with the theme?

I think so. With minimal CSS tuning I can get:
[...]

This would be an improvement over what I did even without autosummary, As it would allow using flat tables and get rid of the manual reformatting of the spaces between the columns. Could you share your "minimal CSS tuning" ?

I agree that finding an automated or semi-automated way to build the tables would be a must. There are multiple challenges involved, I'll have to think more about it. Note for example that both in math and pathlib I modified the short description, so that the tables are as small as possible to not clutter the members overview.

I've basically used

table.docutils {
  width: 95%
}

table.docutils td:first-child {
  width: 200px
}

to set a common table width and a fixed first column. One could likely tune the values further if desired.

Note: .table.docutils seems to be too generic as a selector. In theory, autosummary should set a autosummary class to the table, so that the selectors would be table.autosummary instead. Not sure why it's not the case in the example you've linked.