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:

.. 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. 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
width	length	Width of figure
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)