Improve cross-references between multiple documents configured via latex_documents

[partofthething]

Describe the bug

If I set my latex_documents setting to something like:

latex_documents = [
    ("doc1", "user.tex", "User Guide", "Nick", "manual", False),
    ("doc2", "dev.tex", "Dev Guide", "Nick", "manual", False),
]

but doc2 references sections from doc1, then the LaTeX source built (and therefore the PDF) just shows the reference name (ref1) rather than the section name related to the reference.

It would be nice if at least the section name (or whatever the ref target is) was printed instead of ref1.

It would be better if the links could be set up e.g. using something like the LaTeX xr package (as described here).

It would be best if cross-pdf hyperlinks worked, e.g. using https://ctan.org/pkg/zref

How to Reproduce

conf.py:

project = "Test MultiPDF XREF"
copyright = "2024, Nick Touran"
author = "Nick Touran"
extensions = []
templates_path = ["_templates"]
exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
latex_documents = [
    ("doc1", "user.tex", "User Guide", "Nick", "manual", False),
    ("doc2", "dev.tex", "Dev Guide", "Nick", "manual", False),
]
html_theme = "alabaster"
html_static_path = ["_static"]

index.rst:

Welcome to Test MultiPDF XREF's documentation!
==============================================

.. toctree::
   :caption: Contents:

   doc1
   doc2

doc1.rst:

User Guide
##########

This is the user guide

.. _ref1:

Installation
------------
Here is how you install.

doc2.rst

Developer Guide
###############

This is the dev guide

.. _ref2:

Build enviro
------------
Here is how you build

.. _ref3:

Testing
-------
You can also do internal refs. 

Check out :ref:`ref2` for build environ.

Check out :ref:`ref1` for user guide.

then run: make latex or make latexpdf and observe (in dev.pdf):

The TeX output generated looks like:

You can also do internal refs.

\sphinxAtStartPar
Check out {\hyperref[\detokenize{doc2:ref2}]{\sphinxcrossref{\DUrole{std,std-ref}{Build enviro}}}} for build environ.

\sphinxAtStartPar
Check out \DUrole{xref,std,std-ref}{ref1} for user guide.

Environment Information

Platform:              linux; (Linux-6.6.10-76060610-generic-x86_64-with-glibc2.35)
Python version:        3.10.12 (main, Nov 20 2023, 15:14:05) [GCC 11.4.0])
Python implementation: CPython
Sphinx version:        7.2.6
Docutils version:      0.20.1
Jinja2 version:        3.1.3
Pygments version:      2.17.2

Sphinx extensions

No response

Additional context

No response

[rdzman]

I've run into this issue as well. I build both HTML and LaTeX targets and the references render and link fine in HTML and within a single LaTeX document, but not when referencing one LaTeX document from another. Thanks, @partofthething, for this very clear and concise summary of the issue.