Reference Figures in reStructuredText via Figure Numbers using :numref:

Question

I am currently trying to setup a reStructuredText template. I want to include numbered figures and references to those. So I followed the instructions given in the sphinx documentation ( http://www.sphinx-doc.org/en/stable/markup/inline.html ).

First I included the line

numfig = True

in the file 'conf.py'. I implemented the figure and the reference to it in my file 'rstTemplate.rst' as follows:

.. _my-figure:

.. figure:: images/scen-smartcity.*
    :scale: 50 %
    :alt: smartcity symbol
    :align: center

    This is the caption of the figure (a simple paragraph).

    This is the legend of the figure

Reference to the figure :numref:`(Fig. %s) my-figure`

When I build the html file using make html

Running Sphinx v1.6.1
loading pickled environment... done
building [mo]: targets for 0 po files that are out of date
building [html]: targets for 1 source files that are out of date
updating environment: 0 added, 2 changed, 0 removed
reading sources... [100%] rstTemplate
rstTemplate.rst:: WARNING: duplicate label my-figure, other instance in ><path-to-file>\rstTemplate.rst
<path-to-file>\rstTemplate.rst:: WARNING: duplicate label my-figure, other instance in <path-to-file>\index.rst
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
writing output... [100%] rstTemplate
rstTemplate.rst:41: WARNING: undefined label: (fig. %s) my-figure
<path-to-file>\rstTemplate.rst:41: WARNING: undefined label: (fig. %s) my-figure
generating indices... genindex
writing additional pages... search
copying images... [100%] images/scen-smartcity.svg
copying static files... done
copying extra files... done
dumping search index in English (code: en) ... done
dumping object inventory... done
build succeeded, 6 warnings.

The file index.html then shows the figure, the caption and the reference to it as shown here: output index.html

So the caption shows a nice 'Fig. 1' but the reference using :numref: obviously does not work. I also tried

:numref:`my-figure`

which led to a similar result.

Does anybody know why the reference does not work here?

What is also interesting: all the above mentioned is in my file 'rstTemplate.rst' which I included in the file 'index.rst' via .. include:: rstTemplate.rst. After the html build I recieve the files 'index.html' and 'rstTemplate.html'. Unlike in the 'index.html' version the 'Fig. 1' is not included in the caption of the figure in 'rstTemplate.html'. Might that be related to what is going wrong here?

Thanks in advance.

Answer 1

Assuming your conf.py contains the following:

import sys
import os
html_theme = 'sphinx_rtd_theme'
numfig = True

and your index.rst contains:

.. toctree::
   :maxdepth: 2
   :caption: Home
   :hidden:

 mychapter

Here is a working example for a chapter RST document mychapter.rst:

.. figure:: images/my-image.png
   :name: my-custom-label

This is a caption of the image

This is a reference to :numref:`my-custom-label` bla bla ...

This renders as:

This is a reference to Fig.1 bla bla ...