Automatically tabulate module contents in the docs

[8acee187-d117-413b-8cb9-6e0aaf4fc650]

BPO	39364
Nosy	@JulienPalard, @alexchandel

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields: ```python assignee = None closed_at = None created_at = labels = ['3.8', 'type-feature', '3.7', '3.9', 'docs'] title = 'Automatically tabulate module contents in the docs' updated_at = user = 'https://github.com/alexchandel' ``` bugs.python.org fields: ```python activity = actor = 'xtreak' assignee = 'docs@python' closed = False closed_date = None closer = None components = ['Documentation'] creation = creator = 'alexchandel' dependencies = [] files = [] hgrepos = [] issue_num = 39364 keywords = [] message_count = 1.0 messages = ['360148'] nosy_count = 3.0 nosy_names = ['docs@python', 'mdk', 'alexchandel'] pr_nums = [] priority = 'normal' resolution = None stage = None status = 'open' superseder = None type = 'enhancement' url = 'https://bugs.python.org/issue39364' versions = ['Python 2.7', 'Python 3.5', 'Python 3.6', 'Python 3.7', 'Python 3.8', 'Python 3.9'] ```

[8acee187-d117-413b-8cb9-6e0aaf4fc650]

By default, the docs.python.org page for a module does not list or tabulate the contents of that module. This makes it difficult to browse a module's functions or get a bird's-eye view.

For example, the logging module (https://docs.python.org/3/library/logging.html) has almost 70 functions, methods, and attributes. But it's impossible to scan them without scrolling the entire length of the entry (~18 pages of US letter). Compare to the browsability of itertools (https://docs.python.org/3/library/itertools.html), which manually tabulates its functions in the first section.

docs.python.org should automatically generate a TOC of the module's contents (classes, functions, etc) in the navigation sidebar, below the existing sidebar sections (perhaps in a collapsible section). Rust's documentation does this (example: https://doc.rust-lang.org/std/time/struct.Duration.html), and doc.rust-lang.org also effectively allows the entire page to function as a TOC by providing a "collapse page" button.

[pradyunsg]

This is closely related to an open Sphinx issue: https://github.com/sphinx-doc/sphinx/issues/6316

There's some experimentation being done, toward making this possible for Sphinx projects via Sphinx's extension mechanisms: https://gist.github.com/agoose77/e8f0f8f7d7133e73483ca5c2dd7b907f#gistcomment-4283770

[AA-Turner]

Sphinx 5.2.0 has been released incorporating this feature.

A