feat(gp-sphinx[fonts]): default preload covers heading/italic/bold-code FOUT#34
Open
feat(gp-sphinx[fonts]): default preload covers heading/italic/bold-code FOUT#34
Conversation
…ading/italic/bold-code FOUT The default trio (Sans 400/700 + Mono 400) covered body text and plain code blocks, but Furo / furo-tw.css renders headings and sidebar labels at Sans 500, blockquote.epigraph at Sans 600, em above the fold at Sans 400 italic, and bold inline code at Mono 700. Without preload, those weights downloaded after first paint and the affected text visibly popped in. Add the four faces to the default list. Doctest length and the test_config assertion that hardcoded 3 are bumped to 7. The configuration.md entry for the constant is shortened so the table cell stays readable as the list grows.
Heading/italic/bold-code FOUT no longer requires consumer overrides.
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main #34 +/- ##
=======================================
Coverage 91.57% 91.57%
=======================================
Files 205 205
Lines 16814 16814
=======================================
Hits 15398 15398
Misses 1416 1416 ☔ View full report in Codecov by Sentry. 🚀 New features to boost your workflow:
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
DEFAULT_SPHINX_FONT_PRELOADfrom the existing trio (Sans 400, Sans 700, Mono 400) to cover every face Furo /furo-tw.cssis observed to demand above the fold.Why these specific faces
h1–h6, sidebar labelsblockquote.epigraph<em>body text, announcement-bar emphasis<strong><code>, MyST**\code`**`)These were discovered while debugging first-paint FOUT on libtmux-mcp (tmux-python/libtmux-mcp#36). All four are pulled by Furo's own CSS, not project-specific code, so every gp-furo consumer that renders any of these surfaces ships the same FOUT until they extend the preload list themselves. Moving the additions upstream means new sites get correct first-paint behaviour for free.
Changes
packages/gp-sphinx/src/gp_sphinx/defaults.py: Append the four tuples; reorder so faces are grouped by family with weights ascending. Doctestlen(DEFAULT_SPHINX_FONT_PRELOAD)bumped from3to7. Docstring expanded to name each face's purpose so the constant explains itself.tests/test_config.py:test_merge_sphinx_config_default_fontslength assertion bumped from3to7(matches the existing brittle-by-count style of nearby asserts).docs/configuration.md: Font defaults table cell for the constant shortened to a one-line summary so it stays readable as the list grows.CHANGES: New### What's newentry under## gp-sphinx 0.0.1 (unreleased)describing the FOUT impact.What is NOT in scope
gp-sphinxdefaults intosphinx-fontsitself. The current ownership (gp-sphinx ships the IBM-Plex-flavoured defaults; sphinx-fonts is theme-agnostic and registers the config option) is correct.Test plan
uv run ruff format .— formatting unchangeduv run ruff check . --fix --show-fixes— lint cleanuv run mypy— types clean across 221 source filesuv run pytest --doctest-modules packages/gp-sphinx/src/gp_sphinx/defaults.py— doctest passes with new lengthuv run pytest tests/test_config.py::test_merge_sphinx_config_default_fonts— assertion passes with== 7uv run pytest— full suite green (1473 passed, 161 skipped)