Sphinx扩展在Sphinx中使用GitHub markdown表情符号？ [英] Sphinx extension to use GitHub markdown emoji in Sphinx?

问题描述

问题

我一直在使用）技巧可能应该在Sphinx创建的HTML页面上，而不是在源Markdown文件上（我希望它们仍然可以在GitHub文件中读取）查看器）。

请先谢谢。
问候。

---

2个部分解决方案

• 部分解决方案是。

  
  
  

  使用以下命令安装它：

    pip install sphinxemoji 
    

  然后，在您的狮身人面像的 conf.py ：

   扩展名= [
  '...'，
  'sphinxemoji.sphinxemoji'，
  ] 
    

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

   此文本i包括一个笑脸|：smile：|还有一条蛇！ |：蛇：| 
   
  你不喜欢吗？ |：heart_eyes：| 
    

  如果您想要一致的表情符号样式，可以将其添加到您的 conf中。 py ：

    sphinxemoji_style ='twemoji'
    

  
  

  Problem

  I have been using (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).

  However, CommonMark's support for GitHub flavored Markdown (GFM) is not perfect, and one important feature it lacks are emoji. I searched for other Markdown parser, more specific to GFM, for instance py-gfm, but none of them seem to support emoji.

  For instance, the screenshot below shows the Sphinx output on the left, and the GitHub rendered version on the right:

  So my question is:

  • Does anyone know a Sphinx extension that could add support to GFM-like emoji, in rST and/or Markdown? (ie, emoji written like :boom: this).
  • Or a trick I could use to convert any emoji, eg, :boom:, to a small image? (as that's what GitHub is doing anyway, see for instance the :boom: image) The trick should probably be on the HTML pages created by Sphinx, not on the source Markdown files (I want them to still be readable with GitHub file viewer).

  Thanks in advance. Regards.

  ---

  2 partial solutions

  • A partial solution is this small Python script I wrote, using carpedm20's emoji package. It will convert any :emoji: alias (written :like_this:) to it's UTF-8 version, if possible.

  • I also tried to use pymdownx.emoji package, to write this second script. It will convert any :emoji: alias to a piece of HTML code loading a distant PNG (or SVG) version (from JsDelivr's CDN). Still not perfect, the size/scaling is not good, and even emojis in ... are replaced. (I will improve this).

  Both can be used with this tiny Bash for loop:

  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
  

  Demo:

  • With UTF-8 codes for emojis:
  • With PNG images for emojis (still not perfect):

  解决方案

  Did not find anything out there, so ended up creating an extension.

  Install it with:

  pip install sphinxemoji
  

  Then, in your Sphinx's conf.py:

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

  Then you can start using emoji codes in your documentation (note you need to use bars around the emoji code though):

  This text includes a smily face |:smile:| and a snake too! |:snake:|
  
  Don't you love it? |:heart_eyes:|
  

  If you want consistent emoji style, you can add this to your conf.py:

  sphinxemoji_style = 'twemoji'
  

  这篇关于Sphinx扩展在Sphinx中使用GitHub markdown表情符号？的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！