How to number figures in Sphinx. How to do subfigures

number_figures_in_sphinx.rst

Numbering figures in Sphinx. Subfigures as a bonus

Although the .. figure:: and .. image:: directives in reStructuredText are much easier than their LaTex counterparts, they are also lacking some critical features:

• no automatic numbering
• no subfigures

There are third-party extensions that provide this functionality (numfig and sphinxtr), however this is non-standard.

Here I will describe how to accomplish both of these goals with a vanilla Sphinx install. This has been tested against both HTML and LaTex output.

The Official Method

The documentation recommends decorating your figure with a label (notice the underscore)

.. _some_descriptive_label:

.. figure:: path/to/image.*

    This is a cool caption

Then the figure can be referenced in your document by using the :ref: directive (notice no underscore)

I have a really cool figure at :ref:`some_descriptive_label`

The problem is that the reference will not be a number, but will instead will be a hyperlink to your figure (using the caption text), i.e.

I have a really cool figure at This is a cool caption

Although this works fine for HTML output, it is terrible for paper output (e.g. LaTex).

Workaround

Since the .. figure:: directive has limited functionality, we can abandon it. The caveat is that your figures will be injected into the same numbering sequence as your equations [1].

Start by defining the following convenience substitutions (place these at the bottom of your document or in a separate file that will be included)

.. |beginfigref| raw:: latex

                     \begin{minipage}{\textwidth}


.. |endfigref| raw:: latex

                   \end{minipage}

The only purpose of these is to make LaTex happy.

Then wrap your image into a table together with a .. math:: directive:

+-------------------------------------+
| |beginfigref|                       |
|                                     |
| .. math::                           |
|     :label: some_descriptive_label  |
|                                     |
|     \textbf{This is a cool caption} |
|                                     |
| |endfigref|                         |
+=====================================+
| .. image:: path/to/image.*          |
|                                     |
| More descriptive text, if you want  |
+-------------------------------------+

The .. math:: directive has no actual math in it - instead it's playing the role of a caption! The :label: ensures that the caption is assigned a number. The table glues it all together.

You can reference your image by using the :eq: role:

Please see Figure :eq:`some_descriptive_label`

One advantage of the table is that multiple images can be glued together easily. In other words, we can have subfigures:

+---------------------------------------------------------------------+
| |beginfigref|                                                       |
|                                                                     |
| .. math::                                                           |
|     :label: some_descriptive_label                                  |
|                                                                     |
|     \textbf{This is a cool caption}                                 |
|                                                                     |
| |endfigref|                                                         |
+=====================================+===============================+
| .. image:: path/to/image1.*         | .. image:: path/to/image2.*   |
|                                     |                               |
| (a) more description                | (b) more description          |
+-------------------------------------+-------------------------------+

Footnotes

[1]	Figures and equations should live in the same numbering sequence anyway

How to get rid of the table border, and not to influence other table?