[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: https://github.com/sphinx-doc/sphinx/blob/c5580ebd9115dc8dd1e76a8ac25cea95bc3db2ce/sphinx/latexwriter.py#L467-L471

The if self.in_title or not uri test has remained untouched ever since. https://github.com/sphinx-doc/sphinx/blob/447cd1ab1eb2835b3360854b7ae5ddff0d9a800f/sphinx/writers/latex.py#L1814-L1815

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: https://github.com/sphinx-doc/sphinx/blob/bf431ed0d7ec1423edf72c717887bdea7ad1f277/sphinx/texinputs/sphinxlatexstyletext.sty#L58-L60