Run pdflatex three times during PDF build

[gregmuellegger]

We had a report in #1557 that creating the index for the PDF does not work and that it might be related to how often we run pdflatex during the build.

I'm not latex user so I don't know how reliable this is and I wasn't able to test it locally so far. But based on the interwebz it's often required to run pdflatex multiple times before you get the result you are expecting.

I'm hoping for some input from more experienced latex users.

[agjohnson]

This PR looks fine, but I too would like some input from someone that knows LaTeX well. I understand the second run of pdflatex after makeindex, though I think it's silly, but it definitely seems absurd to have to run it again after that. Hopefully that's not the case, as this is a lot of wasted cycles if not

[ericholscher]

Yea, this all seems like a bit of black magic, and I'd like to really understand why we're doing this as well.

[NoralK]

I am by no means a latex expert but from what I have gathered every time latex runs there are many files created ... among them is the index as flat file. If this flat file is not present or changes during the next processing the index will not be included in the final PDF and a message will state to re-run processing.

With xelatex I generally need to run processing two times, however I have had rare occasions where three runs was needed - I have no idea why. With pdflatex I have seen regularly processing needing 3 runs but to be quiet honest I abandoned pdflatex for xelatex long ago ... the use of any TTF font and UTF-8 character support was a huge draw for me, plus there seems to be more support - but I am a novice here.

Whatever flavour of latex you are running I would suggest posting a message for more input from that community to find out if there is rhyme or reason to PDF generation, with an index.

Noral

[ericholscher]

Closing this, as we haven't gotten any more bug reports about this as far as I can tell. Sounds like it's either an edge case, or a bug lower down the stack.

[jfbu]

I initially added a comment at #1557, but I see now better place would have been here. Moving contents here and suppressing original. Whether xelatex or pdflatex has no relevance for the issue I am reporting:

The Sphinx own documentation displays an aspect of this: the general index is present in the document but there is no "Index" entry either in the PDF bookmarks or at the end of the Table of Contents (it ends with Python Module Index). (sphinx-doc/sphinx#3742)

Starting with upcoming 1.6, Sphinx has switched to using Latexmk. I would recommend it as a robust solution.

Regarding the Table of Contents, any change in section headings or insertion of a new section requires two subsequent pdflatex runs. This is why makeindex must be followed by two pdflatex runs.