如何使用 Sphinx 显示与文本内嵌的键盘按键图片？

Question

在我的 Sphinx 文档中，当我在重组文本中引用它们时，我想显示键盘键的图片。

例如，如果我说：按下 Enter 键。我想在线显示 Enter 键的图片，而不仅仅是 Enter 一词。

我在很多教程中看到过这种图形，用于指代键盘键、菜单选项等。他们是怎么做到的？我可以在 Sphinx 中执行此操作吗？

Answer 1

首先考虑使用语义标记来提高可访问性。 Sphinx 可以渲染角色 :kbd:, :menuselection:, or :guilabel: to HTML or PDF. For HTML output, then you can apply CSS to make the key strokes appear exactly as you would like, even give them the appearance of images without actually making them images. For PDF output, you would use the style \sphinxkeyboard.

您也可以使用Unicode keyboard characters，但您应该确保您在渲染中使用的字体支持该字符。

示例：

return: ⏎
苹果命令：⌘
选项：⌥

AFAIK，Sphinx 及其任何贡献都没有提供任何将文本呈现为图像的功能，aafigure 除外，它从 ASCII 艺术创建图像，但不是您想要的。

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

以上替换给出了原始图像的缩小版本：

如何使用 Sphinx 显示与文本内嵌的键盘按键图片？

How can I show pictures of keyboard keys in-line with text with Sphinx?

python

python-sphinx