Restructuring the stdlib docs

[petersuter]

@hugovk

Some earlier discussions:

Also:

The Python documentation should borrow the idea from the PHP.net

I’d like to start my post with the following phrase: “…Python’s documentation has long been considered to be good for a free programming language…” (devguide.python.org). I understand that the documentation is open-source and free of use, I also acknowledge the fact that the Python docs is ok, however, I believe it can be excellent, therefore I took the example from the php.net where every single function has an obvious explanation and a few good examples underneath it, I believe it’s time to b…

@Nodd

FYI that is also how the numpy documentation is organized (see Array creation routines — NumPy v1.26 Manual for example).

@barneygale

I wonder if it’s possible to add a new Sphinx HTML target that generates a page per defined python ref that includes just the docs from the .. func:: / .. class::
It might help with SEO

(Sphinx autoapi recently implemented this, but switching to that would probably be too big of a migration.)

Sphinx autosummary / autogen can also be used to generate one page per function / class. Example

(autosummary has also been tried to create summary tables for the pathlib docs.)