如何使用Sphinx顯示與文本相符的鍵盤按鍵圖片？

Question

在我的Sphinx文檔中，當我在重構的文本中引用它們時，我想顯示鍵盤按鍵的圖片。

例如，如果我說：點擊Enter鍵。我想顯示一個Enter鍵的圖片，而不是Enter一詞。

我在許多教程中看到過這種圖形，用於指鍵盤按鍵，菜單選項等。他們如何做到這一點？獅身人面像有可能做到這一點嗎？

Answer 1

首先考慮使用語義標記來改善可訪問性。獅身人面像可以將角色:kbd:，:menuselection:或:guilabel:轉換爲HTML。然後，您可以應用CSS使關鍵筆畫完全按照您的喜好顯示，甚至可以在不實際製作圖像的情況下爲其提供圖像外觀。

你也可以使用Unicode keyboard characters，但你應該確保你在渲染時使用的字體支持字符。

例子：

• 回報：⏎
• 蘋果命令：⌘
• 選項：⌥

據我所知，無論是獅身人面像也沒有任何其捐款提供渲染文本的任何能力圖像，除了創建ASCII藝術圖像的aafigure，但不是你想要的。

Answer 2

可以使用reStructuredText substitution機制顯示內嵌圖像。

您可以定義內嵌圖像替換這樣的：

.. |text to substitute| image:: path/to/the/image.ext 

然後你就可以使用，無論你在文檔中喜歡這樣的替換：

random text ... |text to substitute| ... more random text ... 

在呈現的文檔中，|text to substitute|會被path/to/the/image.ext指向的圖像替換（內聯）。

---

在例如，下面的文件...

.. |key inline image| image:: https://cdn1.iconfinder.com/data/icons/hawcons/32/699610-icon-10-file-key-128.png 

This is a |key inline image| inline image, isn't it cool? 

...給出以下結果：

更妙的是，你可以使用image directive選項調整圖像顯示：

.. |key inline image| image:: https://cdn1.iconfinder.com/data/icons/hawcons/32/699610-icon-10-file-key-128.png 
         :height: 15px 
         :width: 50px 

上述取代給出了原始圖像的縮小版本：