LaTeX 中的狮身人面像交叉引用

Question

I have the following reference identified in file A:

.. _my-label:

and I reference it in file B:

this is a reference to file A :ref:`my-label`

This generates a cross-reference as expected when outputting HTML. However, when outputting LaTeX, it does not and I have the classical warning:

LaTeX Warning: Hyper reference `my-label:my-label' on page XX undefined on input line YY.

Is there a LaTeX trick like double compilation or something similar that I am not doing correctly?

Answer 1

I encountered the same issue. HTML compiled without errors for me, but LaTeX compilation did throw the hyperref errors you described. It seems to me that, for some obscure reason, Sphinx does not create the labels that hyperref tries to reference.

---

I came up with the following solution: since I do not know how to include the missing labels, I will just make it so that LaTeX does not look for them anymore. In detail, I am doing this by overwriting the \hyperref command.

I included the following code in my conf.py file:

latex_elements = {
    'preamble': r'''
\renewcommand{\hyperref}[2][]{#2}
'''
    }

This includes the \renewcommand{... in the preamble of the LaTeX document created by Sphinx. It will overwrite the \hyperref command so that it won't try to insert a link, but just print the link text.

Obviously, with this solution, the reference that caused the errors will not appear as hyperlinks in your PDF document, but at least it is compiling without errors.

---

Note

What I described worked perfectly fine for my use case, however, it is described in the Hyperref manual that the \hyperref command can be invoked in two different ways ( \hyperref{URL}{category}{name}{text} and \hyperref[label]{text} ). I am only overwriting the second one, as that seems to be the one that Sphinx is using for cross references. However, not accounting for the first one when overwriting the command might lead to issues in some cases.