Fix PDF build by removing incompatible emoji characters

[nehasanoor2006-collab]

Fixes #2031.

The PDF build uses Sphinx's LaTeX builder with pdflatex, which has limited support for Unicode characters such as emoji. These characters can cause the LaTeX build to fail before the table of contents is fully generated.

Instead of removing the emojis from the documentation source, this change adds a LaTeX-only Sphinx post-transform that sanitizes the affected decorative emoji characters during PDF generation.

This keeps the original source content and HTML output unchanged while preventing the problematic characters from reaching the LaTeX/PDF output.

Testing

• python3 -m nox -s build — passed
• python3 -m nox -s checkqa — passed
• python3 -m sphinx -b latex -d /tmp/pyproject-doctrees source /tmp/pyproject-latex — passed
• git diff --check — passed
• Verified emojis remain in generated HTML.
• Verified targeted emojis are absent from generated LaTeX.
• Full PDF generation could not be run locally because the required TeX toolchain is unavailable.

[merwok]

This removes some personality, even changes output from a tool.

What about this alternative idea: keep the emojis, hook a script that replaces them with ascii emoticons or removes them for the PDF build.

(Please disclose if you use chatbots to create code or messages)

[nehasanoor2006-collab]

Thanks for the suggestion! I agree that removing the emojis from the documentation changes the original presentation. I'll look into keeping the emojis in the source while handling them specifically for the PDF build.
I also used AI assistance while investigating and preparing this contribution.

[webknjaz]

I agree with @merwok. Especially since the GHA workflow gets copied and works in the current format. A PDF-scoped transformer would be preferred. Make sure to have it integrated into the current infra and not run arbitrary low-level disconnected commands for testing as many agents like to do.

[webknjaz]

Could you get rid of the commit that removes the emojis in the first place so that it doesn't contaminate git blame? Also, why does your username say "collab"?

---

Note that in open source, it's common curtesy to talk to people to reach agreement and not replace that with pushing new commits like many agents like to do.

[nehasanoor2006-collab]

Thanks for the feedback. I understand your point about keeping the commit history clean and discussing the approach before pushing changes. I used AI assistance during the investigation and implementation, and I should have discussed the revised approach before pushing the new commit.

The -collab suffix is simply part of my GitHub username; it doesn't indicate any affiliation with the project.

I'll clean up the PR history so the original emoji-removal commit isn't retained, while preserving the final PDF-scoped solution. I'll also make sure to discuss any further changes before pushing them.