Use one header per function on the API docs pages

[asmeurer]

Since the API pages in the docs have a long listing of functions, with the new Furo Sphinx theme, it becomes easier to navigate them when there is a single header per function. Compare the right sidebar on https://docs.sympy.org/dev/modules/core.html which has this with https://docs.sympy.org/dev/modules/ntheory.html which does not.

This will become unnecessary once we use autosummary, but that is not so easy to do for various reasons (see #22589).

The most simple way to do this is to manually list each function in the rst file rather than using automodule. However, the issue with doing this is that we may forget to add new functions to the rst. The coverage_doctest script could help with this but 1) it is not currently working (see #22429) and 2) the current coverage is not 100%, so we couldn't require 100% coverage until we fix this. Having 100% coverage itself is problematic because we would actually want a full coverage documentation to be separate somehow (see #22105). I think long term though we want to do this anyway, so it's not a bad idea to aim for this.

Another thought would be to see if we can modify the autodoc templates so that automodule produces subheaders automatically. I'm not sure how difficult this would be.

See also the discussion at #23159.

[asmeurer]

Alternately, I wonder if there is some way Furo itself could be improved to make this better. I'm working on a glossary (#23293) and noticing an absence of the right toc there too, which is not so easily fixed by just adding redundant headers. Or maybe there already are some other ways to adjust the right sidebar toc? CC @pradyunsg

[pradyunsg]

Furo "just" uses the toc that Sphinx provides -- https://github.com/pradyunsg/furo/blob/c790c6d7a33f45856fa85670a4238a101efefd08/src/furo/theme/furo/page.html#L206 and uses some CSS to make it look better + JS to highlight the current item.

The fact that you can't do this is a known limitation of Sphinx's autodoc at this time, see sphinx-doc/sphinx#6316 (comment). Switching to alternative automated generators (apidoc) might make things easier for you! :)

[pradyunsg]

I dunno how to deal with Glossaries TBH. The only thing that I can think of is basically mimicking what sphinx-apidoc does for injecting the relevant headings.

This stuff might make sense in a separate Sphinx extension, just to make it easier to have tests + CI checks for it.

[asmeurer]

Hmm, so it sounds like I should dig into autodoc and see if it's possible to make it generate the toc without using headers. The headers are redundant on the page, so if we can avoid having them that would actually be better. Or I should just look at how hard fixing that upstream Sphinx issue would be.

[asmeurer]

So great news. Upstream support is being added to Sphinx for this in sphinx-doc/sphinx#10807. I have made a PR cleaning up the now duplicate headers at #24050.