Re-run pdflatex multiple times when generating PDFs

[GaretJax]

Currently pdflatex is run a single time (https://github.com/rtfd/readthedocs.org/blob/master/readthedocs/doc_builder/backends/sphinx.py#L173-L210) but often LaTeX documents need additional runs to get references right.

The Makefile generated by sphinx-build -b latex runs pdflatex 5 times (https://bitbucket.org/birkenfeld/sphinx/src/6a802a4a8bd3b652a91e4effd5e3a7efe2df35bd/sphinx/texinputs/Makefile?at=default#cl-57).

RTD should emulate Sphinx's behavior as closely as possible.

[GaretJax]

#296 and #295 are probably related to this as well.

[GaretJax]

To check if less runs yield the same result. As PDFs are rebuilt on each push we don't want to multiply the load by a factor of 5 if it's not necessary. ;)

[GaretJax]

A possible solutions is to rerun the compilation step only if instructed to do so in the output of the previous run. pdflatex outputs the following message (or similar) when an additional run is needed:

LaTeX Warning: Label(s) may have changed. Rerun to get cross-references right.

[mjkallen]

+1 for a quick fix of this issue. There are currently quite a few projects on RTD which suffer from it. For example:

• http://www.flask-admin.readthedocs.org/builds/bibtexparser/1364742/
• my own https://readthedocs.org/builds/renjin/1381326/
• Google "Rerun to get cross-references right" Passed site:readthedocs.org for more examples

pdflatex needs to be run at least twice as it will write a .aux file on the first run. This file contains TOC entries and page numbers for all the cross-references which get picked up in the second run and inserted into the output.