Referencing figures with numbers in Sphinx and reStructuredText

Question

When writing RST that will be processed with Sphinx, I can't get Sphinx LaTeX output to use figure numbers when referencing figures. For instance, this code:

The lemmings are attacking, as can be seen in :ref:`figlem`.

.. _figlem:

.. figure:: _static/lemming_invasion.* 

   They're coming!

Will be converted into this:

The lemmings are attacking, as can be seen in They're coming!

/image goes here/

Figure 1.1: They're coming!

But what I want is the "standard" LaTeX way of referencing figures, like this:

The lemmings are attacking, as can be seen in Figure 1.1

How do I achieve this? The code I'm currently using is what the Sphinx manual recommends, but it doesn't produce the output I want.

Answer 1

In the latest versions of Sphinx (1.3+), numbering figures and referencing them from text got a bit easier as support for it is now built-in.

In your text, you can do something like:

.. _label:
.. figure:: images/figure.*


At :numref:`label` you can see...

The end result should be something like "At Fig 1.1 you can see...". This technique works both with the default HTML output and the LaTeX output.

In your conf.py file, make sure to set the flag numfig = True. There are also configuration options for the references' text format (numfig_format and numfig_secnum_depth).

References:

• http://www.sphinx-doc.org/en/stable/config.html#confval-numfig
• https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#cross-referencing-figures-by-figure-number

Answer 2

The numfig extension does exactly this. I tried it and it worked for me.

Answer 3

To expand on the accepted answer, you can quickly get this set up as follows. Put the numfig.py file in your source directory. Then open conf.py and uncomment the line that says

sys.path.insert(0, os.path.abspath('.'))

Then add 'numfig' to the extensions list.

To use in your rst document, first label your figure (e.g., fig-main):

.. _fig-main:

.. figure:: main.png

   This is the figure caption.

Finally, you can reference its figure number using the :num: directive, like this:

Refer to the main figure (Figure :num:`fig-main`).

Answer 4

One can use raw latex code, inline. For the example above, a role for raw latex code is first defined and than used to refer to the figure with the \ref{} latex command, and to set a label to the figure with the \label{} latex command.

The following should work:

.. role:: raw-latex(raw)
     :format: latex

The lemmings are attacking, as can be seen in :ref:`figlem`
on figure :raw-latex:`\ref{pic:lem}`.

.. _figlem:

.. figure:: _static/lemming_invasion.* 

   They're coming! :raw-latex:`\label{pic:lem}`

Note that the \label{} command will appear inside the caption in the tex file, but it is still acceptable, at least by pdflatex. Also note that there should be at least one space before :raw-latex.

Answer 5

I think referencing Figures is not yet implemented in reST, but here is workaround http://article.gmane.org/gmane.text.docutils.user/5623 that gets you closer.