LaTeX: let bookmarks use high default depth

Add bookmarksdepth key to latex_elements['sphinxsetup']

6 files changed, 17 insertions, 3 deletions

diff --git a/CHANGES b/CHANGES
index 9dfca4ee3..c8b59e9c5 100644
--- a/CHANGES
+++ b/CHANGES
@@ -75,6 +75,7 @@ Bugs fixed
   change) with late TeXLive 2019
 * #8253: LaTeX: Figures with no size defined get overscaled (compared to images
   with size explicitly set in pixels) (fixed for ``'pdflatex'/'lualatex'`` only)
+* #8881: LaTeX: The depth of bookmarks panel in PDF is not enough for navigation
 
 Testing
 --------
diff --git a/doc/changes.rst b/doc/changes.rst
index 829c7f7ed..3fe902404 100644
--- a/doc/changes.rst
+++ b/doc/changes.rst
@@ -10,7 +10,6 @@ Changelog
 
 .. raw:: latex
 
-   \hypersetup{bookmarksdepth=1}% pdf bookmarks
    \addtocontents{toc}{\protect\setcounter{tocdepth}{1}}%
 
 .. include:: ../CHANGES
diff --git a/doc/conf.py b/doc/conf.py
index f38d03d6d..09397c76b 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -61,11 +61,10 @@ latex_elements = {
     'fontenc': r'\usepackage[LGR,X2,T1]{fontenc}',
     'passoptionstopackages': r'''
 \PassOptionsToPackage{svgnames}{xcolor}
-\PassOptionsToPackage{bookmarksdepth=3}{hyperref}% depth of pdf bookmarks
 ''',
     'preamble': r'''
 \DeclareUnicodeCharacter{229E}{\ensuremath{\boxplus}}
-\setcounter{tocdepth}{3}%    depth of what is kept from toc file
+\setcounter{tocdepth}{3}%    depth of what main TOC shows (3=subsubsection)
 \setcounter{secnumdepth}{1}% depth of section numbering
 ''',
     # fix missing index entry due to RTD doing only once pdflatex after makeindex
diff --git a/doc/latex.rst b/doc/latex.rst
index b736c56ef..ff1af9286 100644
--- a/doc/latex.rst
+++ b/doc/latex.rst
@@ -578,6 +578,17 @@ e.g ``'sphinxsetup': "verbatimwrapslines=false"``.  If setting the
 boolean key to ``true``, ``=true`` is optional.
 Spaces around the commas and equal signs are ignored, spaces inside LaTeX
 macros may be significant.
+Do not use quotes to enclose values, whether numerical or strings.
+
+``bookmarksdepth``
+    Controls the depth of the collapsable bookmarks panel in the PDF.
+    May be either a number (e.g. ``3``) or a LaTeX sectioning name (e.g.
+    ``subsubsection``, i.e. without backslash).
+    For details, refer to the ``hyperref`` LaTeX docs.
+
+    Default: ``5``
+
+    .. versionadded:: 4.0.0
 
 .. _latexsphinxsetuphmargin:
 
diff --git a/sphinx/templates/latex/latex.tex_t b/sphinx/templates/latex/latex.tex_t
index 679660fdd..43ad04b0e 100644
--- a/sphinx/templates/latex/latex.tex_t
+++ b/sphinx/templates/latex/latex.tex_t
@@ -16,6 +16,8 @@
 \ifdefined\pdfimageresolution
     \pdfimageresolution= \numexpr \dimexpr1in\relax/\sphinxpxdimen\relax
 \fi
+%% let collapsable pdf bookmarks panel have high depth per default
+\PassOptionsToPackage{bookmarksdepth=5}{hyperref}
 <% if use_xindy -%>
 %% turn off hyperref patch of \index as sphinx.xdy xindy module takes care of
 %% suitable \hyperpage mark-up, working around hyperref-xindy incompatibility
diff --git a/sphinx/texinputs/sphinx.sty b/sphinx/texinputs/sphinx.sty
index a71c64ffc..cb82dc806 100644
--- a/sphinx/texinputs/sphinx.sty
+++ b/sphinx/texinputs/sphinx.sty
@@ -65,6 +65,8 @@
 \DeclareStringOption[-1]{numfigreset}
 \DeclareBoolOption[false]{nonumfigreset}
 \DeclareBoolOption[false]{mathnumfig}
+\define@key{sphinx}{bookmarksdepth}{\AtBeginDocument{\hypersetup{bookmarksdepth=#1}}}
+\AtBeginDocument{\define@key{sphinx}{bookmarksdepth}{\hypersetup{bookmarksdepth=#1}}}
 % \DeclareBoolOption[false]{usespart}% not used
 % dimensions, we declare the \dimen registers here.
 \newdimen\sphinxverbatimsep