Docs: Add a diagram of pathlib path components

[pganssle]

Add a diagram showing how parent, name, stem, and suffix divide up a path. The example uses /srv/holy/grail.tar.gz so that it also shows that stem removes only the final suffix.

The SVG places stem and suffix above the path and parent and name below it. Stem and suffix use blue and orange, with a half-character gap between their spans. The image uses the documentation theme's existing invert-in-dark-mode class, so it follows both the system preference and the manual theme selector.

The diagram has descriptive alt text giving all four values. HTML and EPUB both use the SVG. An explicit background preserves contrast in EPUB readers that override page colors without applying the documentation theme to images. Such readers retain a white diagram panel rather than placing dark text directly on a black page. The text remains SVG text, and the horizontal margins are balanced.

Validation:

• Full HTML and EPUB builds passed with warnings treated as errors.
• Chromium and Firefox checks passed for automatic light/dark mode and both manual overrides.
• The stem/suffix gap remains visible in both browsers: 12 clear pixels at the image's 776-pixel width, and 4 at 320 pixels.
• Verified that the EPUB archive references and contains the SVG, with the expected alt text.
• All text colors exceed 5:1 against the image background in light mode and 8:1 after the dark-mode filter. Browser checks confirm the label colors exceed WCAG AA's 4.5:1 threshold.
• Pre-commit checks passed for the changed files.

Books.app itself was not available for retesting.

Light mode:

Dark mode:

The diagram and documentation change were developed with AI assistance.

[read-the-docs-community]

Documentation build overview

📚 cpython-previews | 🛠️ Build #35253400 | 📁 Comparing 7e26fb0 against main (415ebff)

  🔍 Preview build  

5 files changed · ± 5 modified

± Modified

• py-modindex.html
• library/ctypes.html
• library/gc.html
• library/pathlib.html
• whatsnew/changelog.html

[hugovk]

I built an EPUB locally with make -C Doc epub && open Doc/build/epub/Python.epub and it looks like this in Books.app on macOS:

Let's make the main path text more visible in dark mode. It looks like contrast ratio of the other text is a bit low as well, we should aim for the WCAG AA level of at least 4.5:1.

[pganssle]

@hugovk I don't have Books.app, but I think it should be improved? Can you check it again?

[hugovk]

HTML

EPUB

[pganssle]

Thanks for the reviews and feedback Hugo and Stan!

[miss-islington-app]

Thanks @pganssle for the PR 🌮🎉.. I'm working now to backport this PR to: 3.14.
🐍🍒⛏🤖

[miss-islington-app]

Thanks @pganssle for the PR 🌮🎉.. I'm working now to backport this PR to: 3.15.
🐍🍒⛏🤖 I'm not a witch! I'm not a witch!

[bedevere-app]

GH-159873 is a backport of this pull request to the 3.15 branch.

[bedevere-app]

GH-159874 is a backport of this pull request to the 3.14 branch.