serhiy-storchaka · GitHub

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

Linked PRs

Read the original on github.com ↗