From 9b2aac68ead15067205470ec28c94af909c080c0 Mon Sep 17 00:00:00 2001 From: jfbu Date: Sun, 15 Jul 2018 13:43:13 +0200 Subject: [PATCH] LaTeX: extend to all projects the #3742 fix for PDF builds at RTD Refs: https://github.com/rtfd/readthedocs.org/issues/2857 --- CHANGES | 5 +++++ doc/conf.py | 7 +------ doc/latex.rst | 20 ++++++++++++++++++-- doc/usage/configuration.rst | 17 ++++++++++------- sphinx/texinputs/sphinx.sty | 8 ++++++++ sphinx/writers/latex.py | 2 +- 6 files changed, 43 insertions(+), 16 deletions(-) diff --git a/CHANGES b/CHANGES index d7761f542..9f9a7b9ee 100644 --- a/CHANGES +++ b/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 ---------- diff --git a/doc/conf.py b/doc/conf.py index 732c4d4a0..31cb8e478 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -64,12 +64,7 @@ latex_elements = { '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' diff --git a/doc/latex.rst b/doc/latex.rst index cfd6f7d8b..ef0827957 100644 --- a/doc/latex.rst +++ b/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. diff --git a/doc/usage/configuration.rst b/doc/usage/configuration.rst index a0fbe641a..01b67c498 100644 --- a/doc/usage/configuration.rst +++ b/doc/usage/configuration.rst @@ -1727,8 +1727,8 @@ the `Dublin Core metadata `_. 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 diff --git a/sphinx/texinputs/sphinx.sty b/sphinx/texinputs/sphinx.sty index 96be30338..bd8a26a30 100644 --- a/sphinx/texinputs/sphinx.sty +++ b/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} diff --git a/sphinx/writers/latex.py b/sphinx/writers/latex.py index 55d37da79..9c184dc5f 100644 --- a/sphinx/writers/latex.py +++ b/sphinx/writers/latex.py @@ -124,7 +124,7 @@ DEFAULT_SETTINGS = { 'maketitle': '\\maketitle', 'tableofcontents': '\\sphinxtableofcontents', 'atendofbody': '', - 'printindex': '\\printindex', + 'printindex': '\\sphinxprintindex', 'transition': '\n\n\\bigskip\\hrule\\bigskip\n\n', 'figure_align': 'htbp', 'tocdepth': '',