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

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: