agent's sphinx build failed on docstrings with emoji in the summary

TL;DR

Ensure the source files are UTF-8 and the build runs in UTF-8 mode; if the toolchain still chokes, strip emoji from generated summaries. Emoji are valid UTF-8, but some build environments cannot handle them.

Error

UnicodeEncodeError: 'charmap' codec can't encode character '\U0001f680' in position 18

Steps

1. Confirm the files are UTF-8 and the failing character is an emoji in a docstring summary. Expected: the exact character and location known.
2. Set the source encoding and UTF-8 mode: source_encoding = 'utf-8-sig' in conf.py and PYTHONUTF8=1 for the build process. Expected: the process can represent the character.
3. If the error persists in a specific writer (often LaTeX or PDF paths), configure the agent to strip or replace emoji in generated docstring summaries. Expected: the problematic writer never sees the character.
4. Rebuild. Expected: the build passes the previously failing docstring.

When to use

• Sphinx fails on emoji in docstrings
• A docs agent adds emoji to summaries
• The failure is an encode error naming a specific character

When not to use

• The error is a decode error on file read (a file encoding problem)
• Emoji render fine but look wrong (a font problem)
• The toolchain is LaTeX-only (check the LaTeX emoji support separately)

Tool compatibility

Sphinx 5.x through 8.x; most often seen on Windows builders.

Variant phrasings

emoji in headings break the LaTeX build

Same handling: UTF-8 mode first, strip for the LaTeX writer if needed.

agent keeps re-adding emoji

Constrain the agent's docstring style: no emoji in summaries, period.

Why it happens

Emoji need full UTF-8 pipeline support. One non-UTF-8 link in the chain (locale, writer, font) turns a valid character into a build failure.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_D2ofbdOHLy4fDMoJygnS2w