Provide better CSS selectors for API-documentation content

[pradyunsg]

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

It is fairly difficult to stylise the content produced by autodoc, due to lack of selectors for certain elements.

• All the themes for Sphinx, that stylise autodoc generated content, need to have weird selectors to ensure that autodoc content is stylised correctly. There is no good way to select an autodoc-generated definition list.

  https://github.com/pradyunsg/furo/blob/677d421c54c79845f84c54ee68394dfb4befeafb/src/furo/assets/styles/content/_api.sass#L6
  https://github.com/readthedocs/sphinx_rtd_theme/blob/ddbe6c69ea1c328fd670cd9fd599a235b4a35c80/src/sass/_theme_rst.sass#L427

• There is no way to select only the parameter name in the generated signature or in the generated parameter list.

• There is no way to select only the parameter type annotations in the generated signature or in the generated parameter list.

• There is no way to consistently select for keywords like class while also not selecting the named attributes (both use .property).

  • https://tox.readthedocs.io/en/rewrite/plugins_api.html#tox.execute.request.StdinSource.OFF
  • https://tox.readthedocs.io/en/rewrite/plugins_api.html#tox.execute.request.StdinSource.user_only

Describe the solution you'd like

Provide selectors for these cases, so that this content can be stylised to look good. :)

Describe alternatives you've considered

Not providing these selectors, and maintaining status quo? That's suboptiomal but certainly an option. It is also possible for downstream themes to rewrite whatever output autodoc generates,

Additional context

pdoc3 has IMO very nice signature presentation for API documentation. Presentation like that is not possible with Sphinx, due to the lack of such selectors.

https://pdoc3.github.io/pdoc/doc/pdoc/html_helpers.html

[jakobandersen]

Basically I agree. Part of it may be lack of documentation of some of the more recent changes to make CSS styling easier. After #9672 and #9695 has been merged I'll try to get started on the documentation update.
As the content is generated from many different places in Sphinx (each domain, field list handling, autodoc?, etc.) is may be useful at some point if you can elaborate/enumerate what "these cases" are.

[pradyunsg]

"these cases" are.

These cases refers to the bullets listed above, which are the specific bits of content that can't be selected through the CSS to stylize.

[pradyunsg]

#9740 reminds me that having some data members that lists the number of arguments of a function would help as well!

I think paramers are wrapped in Sphinx 4, so combined with such a member, it should be possible for downstream themes to implement the wrapping that the user is asking for in that issue, while avoiding wrapping behaviour like that for single-argument calls.