Image grid in reStructuredText / Sphinx

Question

I'm using Sphinx to create documentation for a Python project I'm working on. I have three images I would like to display in a 1x3 grid (i.e. all on the same line), and I'm trying to figure out how to do this in reStructuredText. Right now I have

.. image:: _images/report_title.png

.. image:: _images/report_slide1.png

.. image:: _images/report_slide2.png

I thought about trying to build one of the reST tables around them on a single line, but that seemed a little ridiculous. How can I grid these images?

Chris · Accepted Answer · 2012-04-19T14:26:22.557

14

You can specify the width option for each of your images (see the reStructuredText image directive documentation) to be approximately one third or less of the width of the page.

Try, for example

.. image:: _images/report_title.png
   :width: 30%
.. image:: _images/report_slide1.png
   :width: 30%
.. image:: _images/report_slide2.png
   :width: 30%

The lengths allowed in the width (and height) options are discussed here (they essentially correspond to the length units in CSS documents).

edited Apr 19 '12 at 14:26

answered Apr 19 '12 at 13:43

Chris

44,602
16
137
156

2

Thanks Chris. This was my workaround, but it's really surprising that there doesn't seem to be a way to grid images in reST, it's such a basic feature. – jeremiahbuddha Apr 19 '12 at 20:23
1

This is exactly the same as what you would do in HTML or LaTeX isn't it? In this case it makes perfect sense that this is the way to do it and means that there isn't one more mark up recipe to learn. – Chris Apr 20 '12 at 08:08

score 14 · Answer 2 · answered Feb 09 '15 at 18:52

14

The alternate answer is to use directives as aliases to the image.

.. |logo| image:: ../iamges/wiki_logo_openalea.png
   :width: 20pt
   :height: 20pt

Then use the alias inside a table:

 +---------+-----------+
 | |logo|  +  |logo2|  +
 +---------+-----------+

answered Feb 09 '15 at 18:52

Charles Merriam

19,908
6
73
83

1

Tried this but seems not to work, render as hyperlink and not as image. – sorin May 25 '15 at 11:25

score 8 · Answer 3 · answered May 27 '15 at 07:49

8

For the aliasing, I had better luck with:

.. |logo1| image:: logo1.png    
   :scale: 100%
   :align: middle
.. |logo2| image:: logo2.png
   :scale: 50%
   :align: top

+---------+---------+
| |logo1| | |logo2| |
+---------+---------+

answered May 27 '15 at 07:49

Dylan

868
12
21

score 1 · Answer 4 · answered May 31 '22 at 13:35

Use a list-table without border::

.. list-table:: simple image grid
   :class: borderless

   * - .. image:: _images/report_title.png
     - .. image:: _images/report_slide1.png
     - .. image:: _images/report_slide2.png

Works also with "figure" directives, if you want a caption.

score 0 · Answer 5 · answered Mar 11 '19 at 02:34

I provide another reference. If you want to place puml you can try

    +---------------------+----------------------+
    | .. uml:: class.puml | .. uml:: class.puml  +
    |    :scale: 100%     |     :scale: 100%     +
    +---------------------+----------------------+

Image grid in reStructuredText / Sphinx

5 Answers5

Linked