在 Sphinx 中使用 GitHub 降价表情符号的 Sphinx 扩展?
Sphinx extension to use GitHub markdown emoji in Sphinx?
问题
我一直在用 (Python) Sphinx doc, along with CommonMark parser, to write Sphinx documentation containing files written in both reStructuredText and Markdown. So far so good, it works really fine (see this line in an example of Sphinx conf.py
file).
然而,CommonMark 对 GitHub 风味 Markdown (GFM) 的支持并不完美,它缺少的一项重要功能是 emoji。
我搜索了其他 Markdown 解析器,更具体到 GFM,例如 py-gfm,但其中 none 似乎支持表情符号。
For instance, the screenshot below shows the Sphinx output on the left, and the GitHub rendered version on the right:
所以我的问题是:
- 有谁知道可以在 rST and/or Markdown 中添加对类似 GFM 的表情符号的支持的 Sphinx 扩展? (即,像
:boom:
这样写的表情符号)。
- 或者我可以用来将任何表情符号(例如
:boom:
)转换为小图像的技巧? (因为这就是 GitHub 正在做的事情,例如 the :boom:
image)这个技巧可能应该在 Sphinx 创建的 HTML 页面上,而不是在源 Markdown 文件上(我希望它们GitHub 文件查看器仍然可读。
提前致谢。
问候。
2 部分解决方案
部分解决方案是 this small Python script I wrote, using carpedm20's emoji 包。
如果可能,它会将任何 :emoji: 别名(写作 :like_this:) 转换为它的 UTF-8 版本。
我也试过用pymdownx.emoji package, to write this second script。
它会将任何 :emoji: 别名转换为一段 HTML 代码加载远程 PNG(或 SVG)版本(来自 JsDelivr 的 CDN)。仍然不完美,size/scaling 不好,甚至...中的表情符号都被替换了。 (我会改进这个)。
两者都可以与这个微小的 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 图像(仍然不完美):
您无需将表情符号转换为小图片或使用扩展,因为 Sphinx 实际上支持表情符号,因为它们 copy-pasted 开箱即用。
如果您复制任何表情符号并将其添加到文档文件中,您的编辑器可能无法正确显示它,但只要插入了表情符号,它就会显示在您的文档中。
尝试使用警笛表情符号:
我知道这适用于 reStructuredText 文件,所以希望它也适用于 Markdown 文件。
让这更容易的一件事是将您想要在 rst_epilog 中使用的所有表情符号替换为 reStructuredText 文件。这样你就可以在结语中使用这样的东西:
.. |siren| replace::
每次您想在 reStructuredText 文档中使用警报器时,只需使用 |siren|
。
没有找到任何东西,所以结束了 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'
问题
我一直在用 (Python) Sphinx doc, along with CommonMark parser, to write Sphinx documentation containing files written in both reStructuredText and Markdown. So far so good, it works really fine (see this line in an example of Sphinx conf.py
file).
然而,CommonMark 对 GitHub 风味 Markdown (GFM) 的支持并不完美,它缺少的一项重要功能是 emoji。 我搜索了其他 Markdown 解析器,更具体到 GFM,例如 py-gfm,但其中 none 似乎支持表情符号。
For instance, the screenshot below shows the Sphinx output on the left, and the GitHub rendered version on the right:
所以我的问题是:
- 有谁知道可以在 rST and/or Markdown 中添加对类似 GFM 的表情符号的支持的 Sphinx 扩展? (即,像
:boom:
这样写的表情符号)。 - 或者我可以用来将任何表情符号(例如
:boom:
)转换为小图像的技巧? (因为这就是 GitHub 正在做的事情,例如 the:boom:
image)这个技巧可能应该在 Sphinx 创建的 HTML 页面上,而不是在源 Markdown 文件上(我希望它们GitHub 文件查看器仍然可读。
提前致谢。 问候。
2 部分解决方案
部分解决方案是 this small Python script I wrote, using carpedm20's emoji 包。 如果可能,它会将任何 :emoji: 别名(写作 :like_this:) 转换为它的 UTF-8 版本。
我也试过用pymdownx.emoji package, to write this second script。 它会将任何 :emoji: 别名转换为一段 HTML 代码加载远程 PNG(或 SVG)版本(来自 JsDelivr 的 CDN)。仍然不完美,size/scaling 不好,甚至...中的表情符号都被替换了。 (我会改进这个)。
两者都可以与这个微小的 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 图像(仍然不完美):
您无需将表情符号转换为小图片或使用扩展,因为 Sphinx 实际上支持表情符号,因为它们 copy-pasted 开箱即用。
如果您复制任何表情符号并将其添加到文档文件中,您的编辑器可能无法正确显示它,但只要插入了表情符号,它就会显示在您的文档中。
尝试使用警笛表情符号:
我知道这适用于 reStructuredText 文件,所以希望它也适用于 Markdown 文件。
让这更容易的一件事是将您想要在 rst_epilog 中使用的所有表情符号替换为 reStructuredText 文件。这样你就可以在结语中使用这样的东西:
.. |siren| replace::
每次您想在 reStructuredText 文档中使用警报器时,只需使用 |siren|
。
没有找到任何东西,所以结束了 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'