LaTeX: the \label in a figure should be immediately after \caption, not after legend.

[jfbu]

Subject: a figure may have a legend. This consists of arbitrary body elements after the caption.

Currently the LaTeX writer inserts the \label right before the end of the figure environment (or wrapfigure, sphinxfigure-in-table). But, theoretically, the legend contents could contain for example a table having itself a caption. Then the \label inserted after it will result to document hyperlinks inserted by Sphinx to point to the table in the legend not to the image at top of figure environment.

Proof of concept:

edit: the screenshot was taken with #3702 applied. Without it the very last words caption code are slightly shifted down, because the interline spacing is not correct for the last paragraph.

Source:

Welcome to FOO's documentation!
===============================

.. figure:: more.png
   :name: afigure

   This is the caption.

   This is some legend which contains a table.

   Here is some random extra paragraph for filling up.

   Again some random paragraph and now the table:

   .. table:: A table in a legend of a figure
      :name: atable

      ===== ===== =====
      A     B     C
      ===== ===== =====
      a     b     c
      ===== ===== =====

   Notice also that the small font size does not apply to the table
   caption, due to some hard-coded ``\normalsize`` in LaTeX's caption code.

Now the link to the figure: :ref:`incorrect <afigure>`. It actually brings us
to the table.

• Sphinx version: 1.5.5

[jfbu]

Also, we notice that the table caption is incorrect it uses Fig. 2 like for a figure.

[jfbu]

Fixed at 9875a57