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

Question

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

例如,如果我说:点击Enter键.我想在线显示Enter键的图片,而不是单词Enter.

我在许多教程中都看到过这种图形,用于引用键盘按键,菜单选项等.他们是如何做到这一点的？我可以在Sphinx中这样做吗？

Answer 1

首先考虑使用语义标记来改善可访问性.Sphinx可以渲染角色:kbd:,:menuselection:或:guilabel:到HTML.然后你可以应用CSS来使键击笔画完全按照你想要的方式显示,甚至可以让它们看起来没有实际制作图像.

您也可以使用Unicode键盘字符,但应确保在渲染中使用的字体支持该字符.

例子:

• 回报:⏎
• Apple命令:⌘
• 选项:⌥

AFAIK,Sphinx及其任何贡献都没有提供任何渲染文本到图像的能力,除了从ASCII艺术创建图像但不是你想要的图像.

Answer 2

可以使用reStructuredText替换机制来显示内嵌图像.

您可以像这样定义内联图像替换:

.. |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指令选项来调整图像显示:

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

上面的替换提供了原始图像的缩小版本: