LaTeX: extend to all projects the sphinx-doc#3742 fix for PDF builds at RTD

Refs: readthedocs/readthedocs.org#2857

Author: jfbu

CHANGES

@@ -143,6 +143,11 @@ Features added
   for mathjax
 * #4362: latex: Don't overwrite .tex file if document not changed
 * #1431: latex: Add alphanumeric enumerated list support
+* Extend to all projects not using the Sphinx LaTeX Makefile a workaround for
+  `issue rtfd/readthedocs.org#2857`__ about insufficient number of
+  ``pdflatex`` runs for index to show up in PDF bookmarks (refs: #3742)
+
+  __ https://github.com/rtfd/readthedocs.org/issues/2857
 
 Bugs fixed
 ----------

doc/conf.py

@@ -64,12 +64,7 @@
     'passoptionstopackages': '\\PassOptionsToPackage{svgnames}{xcolor}',
     'preamble': '\\DeclareUnicodeCharacter{229E}{\\ensuremath{\\boxplus}}',
     'fvset': '\\fvset{fontsize=auto}',
-    # fix missing index entry due to RTD doing only once pdflatex after makeindex
-    'printindex': r'''
-\IfFileExists{\jobname.ind}
-             {\footnotesize\raggedright\printindex}
-             {\begin{sphinxtheindex}\end{sphinxtheindex}}
-''',
+    'printindex': '\\footnotesize\\raggedright\\sphinxprintindex',
 }
 latex_show_urls = 'footnote'
 

doc/latex.rst

@@ -55,7 +55,7 @@ example::
    \setlength{\cftsecnumwidth}{1.25cm}
    ''',
        'fncychap': r'\usepackage[Bjornstrup]{fncychap}',
-       'printindex': r'\footnotesize\raggedright\printindex',
+       'printindex': r'\footnotesize\raggedright\sphinxprintindex',
    }
    latex_show_urls = 'footnote'
 
@@ -399,6 +399,21 @@ Macros
   :file:`sphinxmanual.cls` and :file:`sphinxhowto.cls`.
 - the citation reference is typeset via ``\sphinxcite`` which is a wrapper
   of standard ``\cite``.
+- regarding the general index, the :confval:`latex_elements` dictionary has a
+  ``'printindex'`` key which defaults to ``'\\sphinxprintindex'``.  It often
+  proves advantageous to use::
+
+    'printindex': '\\footnotesize\\raggedright\\sphinxprintindex',
+
+  especially if the index contains long entries. The LaTeX class for Japanese
+  ``'manual'``-type documents already does the font size and text
+  justification change, so the above is not needed then.
+
+  .. tip::
+
+     Advanced LaTeX users can also, via :confval:`latex_additional_files`, use
+     a custom :file:`python.ist` style file for :program:`makeindex` to modify
+     the looks of the general index.
 
 Environments
 ~~~~~~~~~~~~
@@ -453,7 +468,8 @@ Environments
 - the bibliography uses ``sphinxthebibliography`` and the Python Module index
   as well as the general index both use ``sphinxtheindex``; these environments
   are wrappers of the ``thebibliography`` and respectively ``theindex``
-  environments as provided by the document class (or packages).
+  environments, needed mainly to insert a corresponding entry in the PDF
+  bookmarks and table of contents.
 
   .. versionchanged:: 1.5
      formerly, the original environments were modified by Sphinx.

doc/usage/configuration.rst

@@ -1727,8 +1727,8 @@ the `Dublin Core metadata <http://dublincore.org/>`_.
 Options for LaTeX output
 ------------------------
 
-These options influence LaTeX output. Refer to :doc:`/latex` for more
-information.
+These options influence LaTeX output. For customization of LaTeX
+macros and environments, see also :doc:`/latex`.
 
 .. confval:: latex_engine
 
@@ -2108,11 +2108,14 @@ information.
            Remove unneeded ``{}`` after ``\\hrule``.
 
      ``'printindex'``
-        "printindex" call, the last thing in the file, default
-        ``'\\printindex'``.  Override if you want to generate the index
-        differently or append some content after the index. For example
-        ``'\\footnotesize\\raggedright\\printindex'`` is advisable when the
-        index is full of long entries.
+        "printindex" call, the last thing in the file.
+
+        .. versionchanged:: 1.8
+           Former default ``'\\printindex'`` now ``'\\sphinxprintindex'``.
+           This macro works around an issue__ with PDF builds at RTD doing too
+           few ``pdflatex`` runs.
+
+           __ https://github.com/rtfd/readthedocs.org/issues/2857
 
      ``'fvset'``
         Customization of ``fancyvrb`` LaTeX package. Defaults to

sphinx/texinputs/sphinx.sty

@@ -459,6 +459,14 @@
   }
 \fi
 
+% provide \sphinxprintindex as variant of \printindex designed to workaround
+% rtfd/readthedocs.org#2857 regarding "Index" entry in PDF bookmarks
+\newcommand*{\sphinxprintindex}{%
+    \IfFileExists{\jobname.ind}
+        {\printindex}
+        {\begin{sphinxtheindex}\end{sphinxtheindex}}%
+}%
+
 % make commands known to non-Sphinx document classes
 \providecommand*{\sphinxtableofcontents}{\tableofcontents}
 \ltx@ifundefined{sphinxthebibliography}

sphinx/writers/latex.py

@@ -124,7 +124,7 @@
     'maketitle':       '\\maketitle',
     'tableofcontents': '\\sphinxtableofcontents',
     'atendofbody':     '',
-    'printindex':      '\\printindex',
+    'printindex':      '\\sphinxprintindex',
     'transition':      '\n\n\\bigskip\\hrule\\bigskip\n\n',
     'figure_align':    'htbp',
     'tocdepth':        '',