Sphinx 扩展在 Sphinx 中使用 GitHub 降价表情符号？

Question

问题

我一直在使用(Python) Sphinx doc 和CommonMark 解析器来编写包含用reStructuredText 和Markdown 编写的文件的Sphinx 文档。到目前为止一切顺利，效果非常好 (see this line in an example of Sphinx conf.py file)。

然而，CommonMark 对 GitHub 风格的 Markdown (GFM) 的支持并不完美，它缺少的一项重要功能是 emoji。 我搜索了其他 Markdown 解析器，更具体到 GFM，例如 py-gfm，但它们似乎都不支持表情符号。

例如，下面的屏幕截图在左侧显示了 Sphinx 输出，在右侧显示了 GitHub 渲染版本：

所以我的问题是：

• 有谁知道可以在 rST 和/或 Markdown 中添加对类似 GFM 的表情符号的支持的 Sphinx 扩展？ （即，像 :boom: 这样写的表情符号）。
• 或者我可以用来将任何表情符号（例如:boom:）转换为小图像的技巧？ （因为这就是 GitHub 正在做的事情，例如，参见 the :boom: image）这个技巧可能应该在 Sphinx 创建的 HTML 页面上，而不是在源 Markdown 文件上（我希望它们仍然可以通过 GitHub 文件查看器读取）。

提前致谢。 问候。

---

2个部分解决方案

• 部分解决方案是我写的this small Python script，使用carpedm20's emoji 包。 如果可能，它会将任何 :emoji: 别名（写为 :like_this:) 转换为其 UTF-8 版本。

• 我也试过用pymdownx.emoji包，写this second script。 它将任何 :emoji: 别名转换为一段 HTML 代码，加载一个遥远的 PNG（或 SVG）版本（来自 JsDelivr 的 CDN）。仍然不完美，大小/缩放不好，甚至...中的表情符号都被替换了。 （我会改进）。

两者都可以与这个小型 Bash for 循环一起使用：

BUILDDIR=_build/html  # Adapt to the location of your Sphinx output
for i in "$BUILDDIR"/*.html; do
    emojize.py "$i" > "$i".new
    # or emojize_pngorsvg.py "$i" > "$i".new
    wdiff -3 "$i" "$i".new;
    mv -vf "$i".new "$i"
done

演示：

• 使用 UTF-8 编码的表情符号：
• 带有表情符号的PNG图像（仍然不完美）：

Answer 1

没有找到任何东西，所以结束了creating an extension。

安装它：

pip install sphinxemoji

然后，在你的 Sphinx 的conf.py：

extensions = [
    '...',
    'sphinxemoji.sphinxemoji',
]

然后您可以开始在文档中使用表情符号代码（请注意，您需要在表情符号代码周围使用条形）：

This text includes a smily face |:smile:| and a snake too! |:snake:|

Don't you love it? |:heart_eyes:|

如果您想要一致的表情符号风格，可以将其添加到您的conf.py：

sphinxemoji_style = 'twemoji'

Answer 2

您无需将表情符号转换为小图像或使用扩展程序，因为 Sphinx 实际上支持表情符号，因为它们是开箱即用的复制粘贴。

如果您复制任何表情符号并将其添加到文档文件中，您的编辑器可能无法正确显示它，但只要插入了表情符号，它就会显示在您的文档中。

用警笛表情符号试试吧：

?

我知道这适用于 reStructuredText 文件，所以希望它也适用于 Markdown 文件。

使这更容易的一件事是在您的rst_epilog 中为 reStructuredText 文件替换您想要使用的所有表情符号。这样您就可以在 Epilog 中使用类似的内容：

.. |siren| replace:: ? 

每次您想在 reStructuredText 文档中使用警报器时，只需使用 |siren|。