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 A
Image B Image B
Image C 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 A
Image B Image B
Image C Image C

Fig. 2 Image spanning multiple columns: AA|BC#


Image A Image A
Image B Image B
Image C Image C

Fig. 3 Image spanning multiple rows: AB|AC#


Figure A Figure A
Figure B Figure B
Figure C Figure C
Figure D Figure D
Figure E Figure E

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


Figure A Figure A
Figure B Figure B
Figure C Figure C

Fig. 5 Sub-figure with captions below#


Figure A
Figure B
Figure C

Fig. 6 Sub-figure with no captions#


Figure A Figure A
Figure B Figure B
Figure C Figure C
Figure D Figure D
Figure E Figure E

Fig. 7 Sub-figure with adaptive layouts#


Figure A Figure A
Figure B Figure B

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