sphinx-subfigure

A sphinx extension to create figures with multiple images:

• Provides a simple format for complex image layouts.

• Supports HTML fully, with responsive layouts, for different screen sizes

  • LaTeX is supported, except for images that span multiple rows.

  • degrades gracefully for other formats.

• Supports figure numbering and referencing.

• Supports image sub-captions, via alt text.

Usage

Install sphinx-subfigure with pip install sphinx-subfigure, then add sphinx_subfigure to your conf.py file’s extensions variable:

extensions = ["sphinx_subfigure"]

numfig = True  # optional

Now add a subfigure directive to your document. For example, to simply place two images side-by-side:

.. subfigure:: AB

   .. image:: imageA.png

   .. image:: imageB.png

Or, for a more complex, responsive layout:

.. subfigure:: AA|BC
   :layout-sm: A|B|C
   :gap: 8px
   :subcaptions: above
   :name: myfigure
   :class-grid: outline

   .. image:: imageA.png
      :alt: Image A

   .. image:: imageB.png
      :alt: Image B

   .. image:: imageC.png
      :alt: Image C

    Figure Caption

1. Each image is automatically assigned an area identifier (A, B, C, etc.).

2. Layouts are formed by composing the areas into a grid, with rows delimited by |.

3. Each area must be used exactly once in the layout, and form a single rectangle.

4. “Empty” areas can be designated with .

5. Spaces in the layout are ignored, so they can be used for visual alignment.

6. Additional layouts can be defined with :layout-sm:, :layout-lg:, :layout-xl:, and :layout-xxl:, for different screen sizes (HTML only).

Image A

Image B

Image C

Fig. 1 Figure Caption

The figure can now be referenced in the document:

:ref:`myfigure`, :numref:`myfigure`

Figure Caption, Fig. 1

Options

Options for subfigure directive:

name	type	description
layout-sm	string	Layout for small screens
layout-lg	string	Layout for large screens
layout-xl	string	Layout for extra large screens
layout-xxl	string	Layout for extra extra large screens
gap	length	Space between image areas (a unitless number is taken as px)
width	length	Width of figure (a unitless number is taken as px)
align	left|center|right	Alignment of figure
subcaptions	above|below	Position of image captions
name	string	Label name of the figure
class	space-delimited	CSS class(es) for the figure
class-grid	space-delimited	CSS class(es) for the grid
class-area	space-delimited	CSS class(es) for each area

More Examples

Image A

Image B

Image C

Fig. 2 Image spanning multiple columns: AA|BC

---

Image A

Image B

Image C

Fig. 3 Image spanning multiple rows: AB|AC

---

Figure A

Figure B

Figure C

Figure D

Figure E

Fig. 4 Sub-figure with empty area: A.B|CDE

---

Figure A

Figure B

Figure C

Fig. 5 Sub-figure with captions below

---

Fig. 6 Sub-figure with no captions

---

Figure A

Figure B

Figure C

Figure D

Figure E

Fig. 7 Sub-figure with adaptive layouts

---

Figure A

Figure B

Fig. 8 Sub-figure using myst-parser syntax: ![alt](image.png)