Merge pull request #5239 from jfbu/latex_revert_5181_RTDbug_workaround

Revert "LaTeX: extend to all projects the #3742 fix for PDF builds at RTD"

Author: jfbu

doc/conf.py

@@ -64,7 +64,12 @@
     'passoptionstopackages': '\\PassOptionsToPackage{svgnames}{xcolor}',
     'preamble': '\\DeclareUnicodeCharacter{229E}{\\ensuremath{\\boxplus}}',
     'fvset': '\\fvset{fontsize=auto}',
-    'printindex': '\\footnotesize\\raggedright\\sphinxprintindex',
+    # 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}}
+''',
 }
 latex_show_urls = 'footnote'
 latex_use_xindy = True

doc/latex.rst

@@ -55,7 +55,7 @@ example::
    \setlength{\cftsecnumwidth}{1.25cm}
    ''',
        'fncychap': r'\usepackage[Bjornstrup]{fncychap}',
-       'printindex': r'\footnotesize\raggedright\sphinxprintindex',
+       'printindex': r'\footnotesize\raggedright\printindex',
    }
    latex_show_urls = 'footnote'
 
@@ -399,23 +399,6 @@ 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 :program:`makeindex` style file :file:`python.ist`, or a custom
-     :program:`xindy` style file :file:`sphinx.xdy` (see
-     :confval:`latex_use_xindy`) in order to modify how the general index is
-     typeset.
 
 Environments
 ~~~~~~~~~~~~
@@ -470,8 +453,7 @@ 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, needed mainly to insert a corresponding entry in the PDF
-  bookmarks and table of contents.
+  environments as provided by the document class (or packages).
 
   .. versionchanged:: 1.5
      formerly, the original environments were modified by Sphinx.

doc/usage/configuration.rst

@@ -1763,8 +1763,8 @@ the `Dublin Core metadata <http://dublincore.org/>`_.
 Options for LaTeX output
 ------------------------
 
-These options influence LaTeX output. For customization of LaTeX
-macros and environments, see also :doc:`/latex`.
+These options influence LaTeX output. Refer to :doc:`/latex` for more
+information.
 
 .. confval:: latex_engine
 
@@ -2173,14 +2173,11 @@ macros and environments, see also :doc:`/latex`.
            Remove unneeded ``{}`` after ``\\hrule``.
 
      ``'printindex'``
-        "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
+        "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.
 
      ``'fvset'``
         Customization of ``fancyvrb`` LaTeX package.  Currently, Sphinx uses

sphinx/texinputs/sphinx.sty

@@ -462,14 +462,6 @@
   }
 \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':      '\\sphinxprintindex',
+    'printindex':      '\\printindex',
     'transition':      '\n\n\\bigskip\\hrule\\bigskip\n\n',
     'figure_align':    'htbp',
     'tocdepth':        '',