Improve the styling of the conformance results page by ngnpope · Pull Request #2307 · python/typing

ngnpope

Issues Identified

Looking at the conformance results page, there were a number of issues that I noticed:

Inconsistent column widths as type checkers are added or removed
Type checker columns are in an arbitrary order
Scrolling down the page, it is hard to remember which column is for which type checker
It is also hard to see which row you're looking at in larger blocks of tests
Only a root template with all other elements as strings joined in Python
The markup didn't validate - duplicate id attributes, <span> parent of <p>
<th> used for all table cells, not only header cells
Styling is over-complicated with excessive class attributes
All cells have a pointer cursor, even if there is no tooltip (or other action)
Tooltips defined using excess elements, positioning is poor and overflows the viewport
Lots of non-breaking spaces used instead of padding
Inconsistent use of markdown code spans in notes

List of Changes

This pull request aims to improve the generated output and make it easier to maintain.

The following changes have been made:

Switch to using tomllib from the standard library instead of tomli
- Dependency not needed as conformance/pyproject.toml has requires-python = "==3.12.*"
Use jinja2 for templates instead of manually joining lists of tags
- Moved stylesheet into a separate file for ease of maintenance
Use better markup for improved accessibility and semantics
- Only use <th> for heading cells, not all table cells
- Use <thead> for the header row with type checker names
- Use separate <tbody> for each group of tests
- Make use of scope attributes for header cells
- Make use of <colgroup> and <col> to reduce excess class attributes
- Reduce the number of elements required for tooltip implementation
Fix issues with styling, including:
- Remove unused CSS rules
- Calculate column widths based on number of type checkers
- Make the table header sticky so it remains visible as the page scrolls
- Add a hover effect to the rows to aid scanning across columns
- Make use of more advanced selectors to reduce excess class attributes
- Use the help cursor instead of pointer, and only where there are tooltips
- Replace the use of non-breaking spaces with padding
- Add asterisk if a pass with notes using CSS only
- Various improvements, e.g. use CSS variables for colors, avoid use of pixel units
- Added a theme selector and support for light/dark (and auto) modes
  - CSS-only based implementation for switching using light-dark(), etc.
  - A small amount of JS for theme persistence
- Added an emoji favicon to make it easier to spot in the browser: 📘 (Can be changed.)
Add markdown rendering of notes in the tooltip
- Improves readability of many notes
- Most notes already used code spans, others have been updated
- Links in notes have been made to be clickable
Added summary rows to each test group and a total footer row at the end of the table
- Use 1 for a pass and 0.5 for a partial result

Passes validation on validator.w3.org (with the exception of a known bug in the validator for nested CSS) and also scores 100 for performance, accessibility, and SEO in Google Chrome DevTools Lighthouse tool.

Future Ideas

Add a footer with the current git hash when the results were generated
Link to conformance test case source files in GitHub from each item in the first column
Add a workflow to publish the results via GitHub Pages
- Would need to be done by someone with access to configure settings
- Current workaround is to use one of these links:
  - https://htmlpreview.github.io/?https://github.com/python/typing/blob/main/conformance/results/results.html
  - https://html-preview.github.io/?url=https://github.com/python/typing/blob/main/conformance/results/results.html
- Alternative could be to publish somehow alongside https://typing.python.org/

AI Disclosure

No AI was involved in creating this pull request.

Screenshots

First Load

Light	Dark

Sticky Table Header

Light	Dark

Tooltip Rendering

Light	Dark