Replace emoji short names with their corresponding emojis in Sphinx documentation.
The short names we are familiar with (e.g. the ones used on sites like GitHub) are not inline with the CLDR short names defined in the Unicode standard. This makes mapping short codes to emojis a bit of a challenge. So, I punt on this issue, and defer to the emoji package created by Taehoon Kim and Kevin Wurster. Their wonderful library does the heavy lifting.
This extension amounts to a find-and-replace. Find the short name, replace it with the
appropriate emoji. It works with both Markdown and reStructuredText.
Emojis are added to documents by sandwiching their short names between colons.
For example, :smile: resolves to 😄. This syntax conflicts with
the way you provide options to directives in Sphinx. And, since the extension
ties into the source-read hook, those directives are yet to be resolved.
As such, if an option shares the same name as an emoji short code, the option
will be replaced by the emoji. Though I am unaware of any case where this happens,
be aware that it is a possibility.
The project is managed with poetry.
To contribute to emoji-shortname, first install poetry. Once installed,
fetch the project dependencies with poetry install. From here, you can
iterate on the code and run the unit tests with poetry run tox pyproject.toml
Simply install the package with your manager of choice (e.g. poetry, pip, etc)
and then add the extension to your sphinx config.py.
extensions = ["emoji_shortname"]