figure¶
Figure is formal more “formal” variant of image used often in academic publications or text books. Unlike the image, it allows to add a caption, be referenced from the other text, etc.
Figure without a caption¶
Basically, you need only to specify a file to display in the figure:: directive argument (please note the space after ::). Without options, figure:: directive displays image as-is, i.e. in original size.
1.. figure:: /img/banana.png
Without a caption, figure looks the same as image.
Figure with caption¶
The main figure’s advantage over image is it supports a caption, a description of the figure. There must be a blank line before the properly indented caption text.
1.. figure:: /img/banana.png
2
3 This is the caption of the figure.
This is the caption of the figure.¶
Tip
Notice there is permalink to this image after the caption. In some themes, it may appear in different positions or after mouse hover the caption.
The blank line is important, otherwise a caption is actually recognized as image file, and causes WARNING: image file not readable: img/banana.pngThisisthecaptionofthefigure.. For example:
1.. figure:: /img/banana.png
2 This is the caption of the figure.
Caption is single paragraph¶
The caption can be arbitrary long, but limited to a single paragraph.
1.. figure:: /img/banana.png
2
3 Very very long caption. Lorem occaecat tempor incididunt culpa fugiat labore tempor veniam occaecat veniam reprehenderit eu Lorem magna. Do fugiat dolore sit fugiat sint enim laboris aute laboris proident. Veniam ullamco mollit exercitation cupidatat et nulla reprehenderit. Qui cillum in nulla reprehenderit pariatur proident officia cillum ut esse occaecat adipisicing. Et nulla fugiat sit consectetur velit enim anim dolor. Deserunt veniam esse duis do commodo cupidatat.
Very very long caption. Lorem occaecat tempor incididunt culpa fugiat labore tempor veniam occaecat veniam reprehenderit eu Lorem magna. Do fugiat dolore sit fugiat sint enim laboris aute laboris proident. Veniam ullamco mollit exercitation cupidatat et nulla reprehenderit. Qui cillum in nulla reprehenderit pariatur proident officia cillum ut esse occaecat adipisicing. Et nulla fugiat sit consectetur velit enim anim dolor. Deserunt veniam esse duis do commodo cupidatat.¶
Caption can’t be longer than the first paragraph. Another paragraph inside figure:: directive content is actually a legend (see bellow).
1.. figure:: /img/banana.png
2
3 This is the caption of the figure because it's first paragraph.
4
5 But this is a legend (see bellow).
Figure legend¶
Figure directive also support a legend, arbitrary complex description of a figure. There must be a blank line before the legend.
1.. figure:: /img/noticeboard.png
2
3 This is the caption of the figure (a simple paragraph).
4
5 The legend consists of all elements after the caption. In this case, the legend consists of this paragraph and the following images:
6
7 .. image:: /img/banana.png
8
9 .. image:: /img/rocket.png
10
11 .. image:: /img/cupcake.png
12
13 .. image:: /img/pumpkin.png
This is the caption of the figure (a simple paragraph).¶
The legend consists of all elements after the caption. In this case, the legend consists of this paragraph and the following images:
Without a caption, figure looks the same as image.
Figure options¶
Figure directive support all of the options of the image directive - modifying dimensions or alignment.
1Consectetur cillum ipsum laborum nisi id. Enim sunt fugiat eiusmod commodo proident culpa.
2
3.. figure:: /img/banana.png
4 :width: 25%
5
6.. figure:: /img/rocket.png
7 :height: 200px
8 :align: right
9
10Do aliqua quis non fugiat reprehenderit ut veniam nulla qui quis proident consectetur dolor. Cupidatat occaecat est officia non eu. Cillum dolore elit incididunt ullamco reprehenderit adipisicing tempor aliqua quis minim ullamco qui Lorem magna. Est enim nostrud velit sit proident est ex fugiat. Deserunt nostrud consequat mollit ut occaecat veniam duis veniam duis aliqua laboris ipsum do. Cillum id nostrud sint elit reprehenderit incididunt velit consequat. Duis Lorem nisi ex elit ut et excepteur laboris ex ea cillum.
11
12.. figure:: /img/pumpkin.png
13 :scale: 150%
Consectetur cillum ipsum laborum nisi id. Enim sunt fugiat eiusmod commodo proident culpa.
Do aliqua quis non fugiat reprehenderit ut veniam nulla qui quis proident consectetur dolor. Cupidatat occaecat est officia non eu. Cillum dolore elit incididunt ullamco reprehenderit adipisicing tempor aliqua quis minim ullamco qui Lorem magna. Est enim nostrud velit sit proident est ex fugiat. Deserunt nostrud consequat mollit ut occaecat veniam duis veniam duis aliqua laboris ipsum do. Cillum id nostrud sint elit reprehenderit incididunt velit consequat. Duis Lorem nisi ex elit ut et excepteur laboris ex ea cillum.