SPHINX - numref works for HTML but not for LaTex

Question

I am working on a Sphinx project for software documentation, which includes a lot of figures. I use 'numref' for referring to the pictures. In HTML it works fine. In LaTex I get Fig. ?? There are only a few issues on numref on the web and the answers did not help me. Can anybody tell me what I am doing wrong?

I installed the Sphinx environment with sphinx-quickstart. Relevant lines from my conf.py are:

    # Conf.py

    # Automatic numbering
    numfig = True

    # -- Options for LaTeX output ------------------------------------------------

    latex_elements = {
        # The paper size ('letterpaper' or 'a4paper').
        #
        'papersize': 'a4paper',

        # The font size ('10pt', '11pt' or '12pt').
        #
        'pointsize': '10pt',

        # Additional stuff for the LaTeX preamble.
        # 'preamble': '',

        # Latex figure (float) alignment
        # 'figure_align': 'htbp',
        'figure_align': 'H' # disable floating
    }

    # Grouping the document tree into LaTeX files. List of tuples
    # (source start file, target name, title,
    #  author, documentclass [howto, manual, or own class]).

    latex_documents = [
        (master_doc, 'PDF_Test.tex', 'PDF generation',
         'Niels de Nies', 'manual'),
    ]

My source (index.rst) looks like:

    #########################
    Sphinx numref Test
    #########################

    My first chapter
    ----------------

    The purpose of this test is to get the numref of figures working in LaTex.

    Section 1
    ~~~~~~~~~
    .. figure:: ../images/hippo.png
        :name: hippo

    :numref:`hippo` Hippopotamus    

    The figure above (:numref:`hippo`) shows an illuminated hippopotamus.

    The 'numref' works fine in HTML, but results in Fig. ?? with LaTex

    Below the alternative way using a label. The results are exactly the same:
    Perfect for HTML, but undefined reference for latexpdf

    .. _fig_hippo:

    .. figure:: ../images/hippo.png
        :name: hippo

    :numref:`fig_hippo` Hippopotamus    

On the commandline LaTeX shows:

    === TeX engine is 'pdfTeX'
    Latexmk: Index file 'PDF_Test.idx' was written
    Latexmk: Log file says output to 'PDF_Test.pdf'
    Latexmk: List of undefined refs and citations:
      Reference `index:hippo' on page 1 undefined on input line 111
      Reference `index:hippo' on page 1 undefined on input line 113
    Latexmk: Summary of warnings from last run of (pdf)latex:
      Latex failed to resolve 2 reference(s)
    Latexmk: All targets () are up-to-date

In the generated PDF_Test.tex the following lines are giving the trouble:

    \hyperref[\detokenize{index:hippo}]{Fig.\@ \ref{\detokenize{index:hippo}}} Hippopotamus

    The figure above (\hyperref[\detokenize{index:hippo}]{Fig.\@ \ref{\detokenize{index:hippo}}}) shows an illuminated hippopotamus.

Can anybody please give me a clue how to fix this?

Answer 1

Or, put another way, for :numref: to work properly, the figure requires the caption text. When generating HTML if the caption text is there you see the "Figure 2.1: Hippopotamus" and if you leave it off the HTML :numref: link still works but the caption below the figure is missing. For PDF output, the caption is required. (If you noticed, you also got a missing reference warning from latexpdf.)

Answer 2

It took a lot of time, but finally I found the answer. The sourcecode should look like this:

    .. figure:: ../images/hippo.png
        :name: hippo

        Hippopotamus    

    The figure above (:numref:`hippo`) shows an illuminated hippopotamus.

Shows in HTML and PDF like: