[pvcraven]

Summary

PR 7 of the text improvements: text documentation.

1. New programming guide page: "Drawing Text"

doc/programming_guide/text.rst, linked in the Manual table of contents after Textures. Until now, the guide had no page on text. It covers:

• Choosing a way to draw text: draw_text, Text, TextPool and create_text_sprite, with what each is best for.
• What costs what with Text: creating (~0.6 ms), drawing (~30 µs), moving or recoloring (almost free), and changing the text or style (lays it out again). Setting an unchanged value is free since Skip unneeded Text layouts for unchanged values and with blocks #2921, and with text: groups changes into one layout.
• Batches, with a measured comparison: 20 Text objects drawn one at a time took ~570 µs, and in one batch ~30 µs.
• TextPool and text sprites.
• Fonts:
  • names, and fallback tuples and lists;
  • font file paths and resource handles (since Load font files passed as font_name, and accept lists of names #2922);
  • load_font and using the font's name;
  • the bundled Kenney and Liberation fonts, which have to be loaded with load_kenney_fonts() / load_liberation_fonts().
• Style: bold weights, italic/"oblique", and LinearGradient colors (since Fix Text italic, bold strings, gradient colors, and swallowed errors #2920).
• Layout: anchors, multiline, and measuring text.
• Cameras: a note that text is drawn with the current camera.

Every code example on the page runs, and I checked the font names against what actually loads. One finding from that: on Windows, "Kenney Future Narrow" can't be found by name, because DirectWrite treats it as a narrower width of "Kenney Future". It falls back to the default font. The page has a note: on Windows, use font_name="Kenney Future", stretch="semicondensed", which I verified there. I couldn't check Linux or macOS.

2. Performance tips

The "Text drawing performance" section still called draw_text "the slowest thing aside from disk access". It's now a short list: use Text objects, change position and color freely but not the text, use with text:, use batches, use TextPool, and use text sprites for static text that moves. It links to the new page.

3. draw_text warning and docstring

• Warning: the old text was "draw_text is an extremely slow function". It now says it's much slower than Text objects, "especially for many lines or changing text".
• Docstring: it said Text objects "can be 10-100 times faster". For one unchanged line I measured 31 µs for draw_text against 27 µs for Text.draw(). The difference is in changing text, many lines, and batches, so the docstring now says that and links to the guide. I kept "might be removed in the near future", since that's a project decision.

Checks

• Docs: built with sphinx-build -W, the same as CI's docs-full, with no warnings. All the new page's API and :ref: links resolve. pyglet.text.LinearGradient shows as code without a link, because pyglet's docs don't index it.
• Tests: text tests pass, and ruff is clean.

The changelog has an entry under Unreleased → Misc Changes.

🤖 Generated with Claude Code