1242264 - No subsections in TOC in the PDF generated by readthedocs.io

Status: NEW

(Bugzilla :: Documentation, defect)

Description

[Frédéric Buclin]

This happens for both 5.0.2 and master: all links in the PDF documentation generated by readthedocs.org are not clickable. The PDF generated locally with rst2pdf is fine.

Moreover, the table of content in the PDF for 5.1 generated by RTD has no subsections despite they are listed in the PDF for 5.0 and in all cases by the PDF generated locally with rst2pdf.

Both issue make the navigation in the PDF very hard.

Comment 1

[Gervase Markham [:gerv]]

(In reply to Frédéric Buclin from comment #0)
> This happens for both 5.0.2 and master: all links in the PDF documentation
> generated by readthedocs.org are not clickable. The PDF generated locally
> with rst2pdf is fine.

This works for me in a just-downloaded copy of the RTD PDF in evince...

> Moreover, the table of content in the PDF for 5.1 generated by RTD has no
> subsections despite they are listed in the PDF for 5.0 and in all cases by
> the PDF generated locally with rst2pdf.
> 
> Both issue make the navigation in the PDF very hard.

I don't see subsections in the RTD PDF for either 5.0 or 5.1. Can you check again?

I agree it's a problem. Presumably there's a setting somewhere we need to set.

Gerv

Comment 2

[Gervase Markham [:gerv]]

We have pdf_toc_depth = 5 in conf.py. Perhaps RTD doesn't respect that setting?

https://github.com/rtfd/readthedocs.org/issues/1997 filed.

Gerv

Comment 3

[Gervase Markham [:gerv]]

Seems like RTD uses pdflatex rather than rst2pdf. We can configure the tocdepth with a preamble:

latex_elements = {
...
'preamble': '\setcounter{tocdepth}{2}',
}

I don't particularly want to install 1GB of latex packages just to test this. LpSolit: do you have them installed already?

Gerv

Comment 4

[Frédéric Buclin]

(In reply to Gervase Markham [:gerv] from comment #3)
> I don't particularly want to install 1GB of latex packages just to test
> this. LpSolit: do you have them installed already?

For the same reason as you: no. :) That's why I use rst2pdf.

Comment 5

[Gervase Markham [:gerv]]

OK. Shall we check in the fix speculatively and see what RTD does?

Gerv

Comment 6

[Frédéric Buclin]

I don't know where your command in comment 3 comes from. But if you are confident with it, feel free to test it. In the worst case, we can back it out.

Comment 7

[Gervase Markham [:gerv]]

It comes from http://stackoverflow.com/questions/20073309/how-to-set-sphinx-and-latexpdf-toc-depth , which is linked from the issue linked above.

How many levels of TOC depth do we want? 2 seems like a good number. If so, the magic number is actually, 1 according to that link. I'll check in a patch and we'll see what RTD does.

Gerv

Comment 8

[Gervase Markham [:gerv]]

To ssh://[e-mail]/bugzilla/bugzilla.git
   fdf1156..796b692  master -> master

Gerv

Comment 9

[Gervase Markham [:gerv]]

To ssh://[e-mail]/bugzilla/bugzilla.git
   796b692..dfa6603  master -> master

Gerv

Comment 10

[Frédéric Buclin]

Looks like these 2 commits didn't help.

Comment 11

[Gervase Markham [:gerv]]

It does work locally, so https://github.com/rtfd/readthedocs.org/issues/2333 filed on it not working on readthedocs.io.

Gerv