Feature or enhancement

Proposal

Modernize the HTML generated by pydoc — the pydoc -b/-p server pages and pydoc -w files — by replacing the remaining 1990s-era markup with semantic HTML5 and restyling the pages after the python-docs-theme used by docs.python.org.

This is the unfinished half of gh-54925 (bpo-10716). The first half landed in 3.11 (GH-28651): HTML5 doctype, <font>/bgcolor removed, colors moved to pydoc_data/_pydoc.css. But the markup is still built of layout tables, docstrings are encoded with &nbsp; and <br>, anchors use the obsolete <a name=...>, and the visual design is unchanged ("big coloured rectangles").

Proposed changes

Markup (pydoc.HTMLDoc and the server pages):

• <header>/<section>/<h1>–<h4> instead of layout tables; a flexbox <nav> for the server's navigation bar;
• multi-column lists via CSS columns (responsive, instead of fixed 4 columns);
• docstrings rendered with white-space: pre-wrap instead of &nbsp;/<br>;
• id= anchors instead of <a name=...> (anchor names unchanged, existing links keep working);
• members inherited from other classes are collapsed by default using <details> (requested by Terry Reedy in Modernize pydoc to use better HTML and separate CSS #54925);
• ServerHTMLDoc in xmlrpc.server, which reuses HTMLDoc, is updated to match.

Style sheet (pydoc_data/_pydoc.css, still separate and user-customizable):

• fonts, colors and link styles from the python-docs-theme;
• topic/keyword pages render the help text as docs.python.org-style literal blocks;
• dark mode via prefers-color-scheme;
• :target highlighting for anchors.

Compatibility: HTMLDoc is undocumented but subclassed in the wild, so all method signatures are kept; parameters that no longer make sense are accepted and ignored. Server page titles are unchanged. The markup itself does change, so code scraping the generated HTML needs adjusting.

Note: pydoc -w files referencing no style sheet at all is a separate bug (gh-127276) with an independent fix.

Prior art

• Modernize pydoc to use better HTML and separate CSS #54925, esp. Frédéric Jolliton's checklist (msg246917), followed here
• https://github.com/aroberge/mod_pydoc
• https://github.com/python/python-docs-theme

Linked PRs

• gh-153906: Modernize pydoc HTML output #153909
• gh-153906: Show 'Data' in code formatting #154132