Automatically tabulate module contents in the docs

[alexchandel]

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:

assignee = None
closed_at = None
created_at = <Date 2020-01-16.22:05:46.796>
labels = ['3.8', 'type-feature', '3.7', '3.9', 'docs']
title = 'Automatically tabulate module contents in the docs'
updated_at = <Date 2020-01-17.08:13:58.250>
user = 'https://github.com/alexchandel'

bugs.python.org fields:

activity = <Date 2020-01-17.08:13:58.250>
actor = 'xtreak'
assignee = 'docs@python'
closed = False
closed_date = None
closer = None
components = ['Documentation']
creation = <Date 2020-01-16.22:05:46.796>
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']

[alexchandel]

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: sphinx-doc/sphinx#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