sstirlin/number_figures_in_sphinx.rst

## number_figures_in_sphinx.rst

      
    Raw
  

              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¹.
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


Figures and equations should live in the same numbering sequence anyway↩