Skip to content

Conversation

mhsmith
Copy link
Member

@mhsmith mhsmith commented Feb 12, 2024

A "simple" list is one whose items all consist of a single paragraph, optionally followed by a nested list which is itself simple. Sphinx detects such lists and gives them the simple class, but does not make any other structural changes to the HTML output.

The PEP style sheet currently does nothing with this class. As a result, when a list contains a mixture of single-paragraph and multi-paragraph items, it's common for a paragraph to appear closer to paragraphs of a different item than it is to other paragraphs of the same item. This obscures the logical structure of the text.

This PR fixes that by adding spacing between the items of "complex" (i.e. non-simple) lists, equal to the spacing between regular paragraphs. For example, in PEP 595:

BEFORE Screenshot 2024-02-12 at 20 32 51 AFTER Screenshot 2024-02-12 at 20 33 24

By definition, a simple list cannot contain a complex list. But if a complex list contains a simple list, it is still rendered compactly. For example, in PEP 572:

BEFORE Screenshot 2024-02-12 at 20 34 23 AFTER Screenshot 2024-02-12 at 20 34 40

A multi-level simple list only has the simple class on its top-level element. The rendering of such lists has not changed. For example, in PEP 432 (BEFORE / AFTER):

Screenshot 2024-02-12 at 20 35 56

📚 Documentation preview 📚: https://pep-previews--3662.org.readthedocs.build/

@mhsmith mhsmith requested a review from AA-Turner as a code owner February 12, 2024 20:59
@mhsmith mhsmith mentioned this pull request Feb 12, 2024
4 tasks
@hugovk hugovk added the infra Core infrastructure for building and rendering PEPs label Feb 13, 2024
Copy link
Member

@hugovk hugovk left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks, changes look good with Chrome on macOS and Android.

It might be worth upstreaming these (to Sphinx?) but I'm fine including them here.

@mhsmith
Copy link
Member Author

mhsmith commented Feb 13, 2024

There are already some similar rules upstream in Sphinx's default themes, but the PEP theme has its own independent style sheet which isn't based on any of them.

@JelleZijlstra JelleZijlstra merged commit 433958e into python:main Feb 16, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
infra Core infrastructure for building and rendering PEPs
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants