[LaTeX] URLs/links in sections headers should be hyperlinks

[dbitouze]

Is your feature request related to a problem? Please describe.
URLs/links in sections headers:

• with the HTML output, are hyperlinks,
• with the (LaTeX) PDF output, are not hyperlinks.

Describe the solution you'd like
I'd like URLs/links in sections headers be hyperlinks with the (LaTeX) PDF output, just as they are with the HTML output.

Additional context
Here is a minimal index.rst pointing out the problem:

.. FOO documentation master file, created by
   sphinx-quickstart on Sat Aug 24 18:39:54 2024.
   You can adapt this file completely to your liking, but it should at least
   contain the root `toctree` directive.

FOO documentation
=================

test
====

See the `reStructuredText <https://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html>`_ documentation for details.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

text

[jfbu]

Thanks for report.

Related to #11973.

This behavior dates back to (quasi) the very first installment 17 years ago of a latex writer:

sphinx/sphinx/latexwriter.py

Lines 467 to 471 in c5580eb

	def visit_reference(self, node):
	uri = node.get('refuri', '')
	if self.in_title or not uri:
	self.context.append('')
	elif uri.startswith(('mailto:', 'http:', 'ftp:')):

The if self.in_title or not uri test has remained untouched ever since.

sphinx/sphinx/writers/latex.py

Lines 1814 to 1815 in 447cd1a

	if self.in_title or not uri:
	self.context.append('')

Perhaps the rationale at that time was with problems about "moving arguments being fragile" stuff one reads about in LaTeX's manuals. But current mark-up \sphinxhref is \protected. Ah, I think the problem may also have been with \href argument containing special characters such as #. But # is escaped by Sphinx into \# which is fine (I have not checked since when). And \sphinxhref is configured for some years to be allowed inside arguments of other macros.

Removing the if self.in_title and trying the slightly more challenging input

See the `reStructuredText <https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#field-lists>`_ documentation for details.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Turns out everything works fine: the PDF from make latexpdf proves perfectly functional. The hyperlink works also from inside the table of contents corresponding section entry.

We have to do some resarch to understand in which circumstances we have to be careful about URLs in titles. But overall, the fix here would simply to remove the if self.in_title test.

[jfbu]

We will need to add

\makeatletter
\AtBeginDocument{\pdfstringdefDisableCommands{%
    \let\sphinxhref\@secondoftwo
}}
\makeatother

Note the following pre-existing comment:

sphinx/sphinx/texinputs/sphinxlatexstyletext.sty

Lines 58 to 60 in bf431ed

	\AtBeginDocument{\pdfstringdefDisableCommands{%
	% all "protected" macros possibly ending up in section titles should be here
	% TODO: examine if \sphinxhref, \sphinxurl, \sphinnolinkurl should be handled