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

Submitted by Paul Barker on Nov. 13, 2020, 9:54 a.m. | Patch ID: 177944

Details

Message ID 20201113095431.7425-1-pbarker@konsulko.com
State New
Headers show

Commit Message

Paul Barker Nov. 13, 2020, 9:54 a.m.
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.

Signed-off-by: Paul Barker <pbarker@konsulko.com>
---
 documentation/conf.py | 5 +++++
 1 file changed, 5 insertions(+)

Patch hide | download patch | download mbox

diff --git a/documentation/conf.py b/documentation/conf.py
index 9a0186f35..a8df6e8f8 100644
--- a/documentation/conf.py
+++ b/documentation/conf.py
@@ -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}',
+}

Comments

Nicolas Dechesne Nov. 13, 2020, 10:14 a.m.
On Fri, Nov 13, 2020 at 10:54 AM Paul Barker <pbarker@konsulko.com> wrote:
>
> 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.

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

>
> Signed-off-by: Paul Barker <pbarker@konsulko.com>
> ---
>  documentation/conf.py | 5 +++++
>  1 file changed, 5 insertions(+)
>
> diff --git a/documentation/conf.py b/documentation/conf.py
> index 9a0186f35..a8df6e8f8 100644
> --- a/documentation/conf.py
> +++ b/documentation/conf.py
> @@ -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
>
-=-=-=-=-=-=-=-=-=-=-=-
Links: You receive all messages sent to this group.
View/Reply Online (#634): https://lists.yoctoproject.org/g/docs/message/634
Mute This Topic: https://lists.yoctoproject.org/mt/78226477/3617530
Group Owner: docs+owner@lists.yoctoproject.org
Unsubscribe: https://lists.yoctoproject.org/g/docs/unsub [oe-patchwork@oe-patch.openembedded.org]
-=-=-=-=-=-=-=-=-=-=-=-