Skip to contentSkip to conversation

conf.py: Improve TOC and Outline depth in PDF output

PATCH In review Paul Barker 2 participants 2 messages Nov 13, 2020

lore
Share & tools
lore
#0 lore raw

PATCH 1/1 conf.py: Improve TOC and Outline depth in PDF output

The default PDF output shows only chapter headings in the table of contents and in the outline (aka PDF bookmarks). We should override these defaults to set something more suitable.

With a depth of 2 for the TOC we see both section and subsection headings which is enough to get the list of classes in the reference manual and the list of topics under "Common Tasks" in the development manual. Going to a deeper level would make the TOC unwieldy but we do want to make sure we can navigate more precisely using the outline (commonly shown in a left tab in PDF viewers) so we set the depth to 5 for the outline.

---
 documentation/conf.py | 5 +++++
 1 file changed, 5 insertions(+)
documentation/conf.py +5 -0
index 9a0186f35..a8df6e8f8 100644
@@ -124,3 +124,8 @@ html_last_updated_fmt = '%b %d, %Y'
 
 # Remove the trailing 'dot' in section numbers
 html_secnumber_suffix = " "
+
+latex_elements = {
+    'passoptionstopackages': '\PassOptionsToPackage{bookmarksdepth=5}{hyperref}',
+    'preamble': '\setcounter{tocdepth}{2}',
+}
Signature · 1 line
2.20.1
#1 lore raw
Quoted 5 lines · Paul Barker

The default PDF output shows only chapter headings in the table of contents and in the outline (aka PDF bookmarks). We should override these defaults to set something more suitable.

Quoted 7 lines

With a depth of 2 for the TOC we see both section and subsection headings which is enough to get the list of classes in the reference manual and the list of topics under "Common Tasks" in the development manual. Going to a deeper level would make the TOC unwieldy but we do want to make sure we can navigate more precisely using the outline (commonly shown in a left tab in PDF viewers) so we set the depth to 5 for the outline.

thanks, it is indeed much better! I updated the file here so that everyone can check it:
https://people.linaro.org/~nicolas.dechesne/theyoctoproject.pdf

Quoted 22 lines
---
 documentation/conf.py | 5 +++++
 1 file changed, 5 insertions(+)
documentation/conf.py +5 -1
index 9a0186f35..a8df6e8f8 100644
@@ -124,3 +124,8 @@ html_last_updated_fmt = '%b %d, %Y'
 
 # Remove the trailing 'dot' in section numbers
 html_secnumber_suffix = " "
+
+latex_elements = {
+    'passoptionstopackages': '\PassOptionsToPackage{bookmarksdepth=5}{hyperref}',
+    'preamble': '\setcounter{tocdepth}{2}',
+}
--

2.20.1