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

Question

In my Sphinx documentation, I'd like to show pictures of keyboards keys when I refer to them in the restructured text.

For example, if I say: Hit the Enter key. I'd like to show a picture of the Enter key in-line, instead of just the word Enter.

I have seen this kind of graphics in many tutorials for referring to keyboards keys, menu options etc. How do they do this? Is it possible for me to do this in Sphinx?

Answer 1

Consider first using semantic markup to improve accessibility. Sphinx can render the roles :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.

You could also use Unicode keyboard characters, but you should ensure the font you use in rendering supports the character.

Examples:

• return: ⏎
• Apple command: ⌘
• option: ⌥

AFAIK, neither Sphinx nor any of its contributions provides any capability to render text to images, except for aafigure which creates images from ASCII art but is not what you want.

Answer 2

It is possible to display inline images using the reStructuredText substitution mechamism.

You can define an inline image substitution like this:

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

Then you can use the substitution wherever you like in your document like this:

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

In rendered document, the |text to substitute| will be replaced (inline) by the image pointed by path/to/the/image.ext.

---

In example, the following document...

.. |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?

...gives the following result:

Even better, you can use the image directive options to tweak the image display:

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

The above substitution gives a reduced version of the original image: