PDF document, via LaTeX builder, fails to reference figures

[wrobell]

Describe the bug

I want to produce two PDF documents

1. Main document
2. A report document

Please note that the main document does not reference the report document in its TOC.

When I run sphinx-build then I get the warning

[...]/doc/performance.rst:7: WARNING: Failed to create a cross reference. Any number is not assigned: test-figure

And the report document does not reference the figure properly. However, section reference still works.

If I run sphinx-build 2nd time with -D root_doc=performance option, then the figure reference works.

How to Reproduce

The files to reproduce the issue attached

doc.zip

Environment Information

Reproduced with Sphinx 6.2.0 and Sphinx 7.0.1.

Sphinx extensions

No response

Additional context

No response

[picnixz]

Not very sure whether this is the intended behaviour but this is because the document is not referenced at all that the issue is like that:

sphinx/sphinx/domains/std.py

Lines 1070 to 1076 in d3c91f9

	try:
	figure_id = target_node['ids'][0]
	return env.toc_fignumbers[docname][figtype][figure_id]
	except (KeyError, IndexError) as exc:
	# target_node is found, but fignumber is not assigned.
	# Maybe it is defined in orphaned document.
	raise ValueError from exc

Since your document is an orphan document, it appears that you won't be able to use it like that. Now, I think that you actually need to create two "projects" and include them as follows:

.. index.rst

.. toctree::
   :caption: Title
   :numbered:

   main/index.rst
   performance

In main, you'll find everything you want that should be rendered as the "first" document so you won't export index as a PDF itself, but only main/index.rst. I haven't tested it but it should render properly (although you'll still have a huge document index containing all merged documents together, but this is fine for the HTML output I think).

With the above structure, the numref would work as intended (you will have two distinct figure numbers for the same figure depending on whether you consult the standalone PDF for performance or the merged PDF for index but this is fine).

[wrobell]

@picnixz Thanks for the suggestions. I really prefer to keep these two documents separate (while both of them are part of the HTML version of the documentation).

My current workaround is to generate my documentation in PDF format by running make for PDF twice. Second time I am using make -D root_doc=performance.