Merge branch 'stable'

CHANGES

@@ -58,6 +58,16 @@ Documentation
 Release 1.4.5 (in development)
 ==============================
 
+Incompatible changes
+--------------------
+
+* latex, inclusion of non-inline images from image directive resulted in
+  non-coherent whitespaces depending on original image width; new behaviour
+  by necessity from earlier one in some cases. (ref: #2672)
+* latex, use of ``\includegraphics`` to refer to Sphinx custom variant is
+  deprecated; in future it will revert to original LaTeX macro, custom one has
+  already alternative name ``\sphinxincludegraphics``.
+
 Features added
 --------------
 
@@ -72,6 +82,8 @@ Bugs fixed
 * #2676: (latex) Error with verbatim text in captions since Sphinx 1.4.4
 * #2629: memoir class crashes LaTeX. Fixed ``by latex_keep_old_macro_names=False`` (ref 2675)
 * #2684: `sphinx.ext.intersphinx` crashes with six-1.4.1
+* #2679: ``float`` package needed for ``'figure_align': 'H'`` latex option
+* #2671: image directive may lead to inconsistent spacing in pdf
 
 
 Release 1.4.4 (released Jun 12, 2016)

sphinx/builders/gettext.py

@@ -135,7 +135,7 @@ tzdelta = datetime.fromtimestamp(timestamp) - \
 source_date_epoch = getenv('SOURCE_DATE_EPOCH')
 if source_date_epoch is not None:
     timestamp = float(source_date_epoch)
-    tzdelta = 0
+    tzdelta = timedelta(0)
 
 
 class LocalTimeZone(tzinfo):

sphinx/texinputs/sphinx.sty

@@ -55,6 +55,9 @@
 \RequirePackage{alltt}
 % Display "real" single quotes in literal blocks.
 \RequirePackage{upquote}
+% For the H specifier. Do not \restylefloat{figure}, it breaks Sphinx code
+% for allowing figures in tables.
+\RequirePackage{float}
 
 % Redefine these colors to your liking in the preamble.
 \definecolor{TitleColor}{rgb}{0.126,0.263,0.361}
@@ -815,26 +818,29 @@
  \raggedright}
 {\end{list}}
 
-% Redefine includgraphics for avoiding images larger than the screen size
-% If the size is not specified.
+% Re-define \includegraphics to resize images larger than the line width
+% if the size is not specified.
+% Warning: future version of Sphinx will not modify original \includegraphics,
+% Below custom code will be direct definition of \sphinxincludegraphics, with
+% \py@Oldincludegraphics replaced by direct use of original \includegraphics.
 \let\py@Oldincludegraphics\includegraphics
-
-\newbox\image@box%
-\newdimen\image@width%
-\renewcommand\includegraphics[2][\@empty]{%
-  \ifx#1\@empty%
-    \setbox\image@box=\hbox{\py@Oldincludegraphics{#2}}%
-    \image@width\wd\image@box%
-    \ifdim \image@width>\linewidth%
-      \setbox\image@box=\hbox{\py@Oldincludegraphics[width=\linewidth]{#2}}%
-      \box\image@box%
-    \else%
-      \py@Oldincludegraphics{#2}%
-    \fi%
-  \else%
+\newbox\spx@image@box
+\renewcommand*{\includegraphics}[2][\@empty]{%
+  \ifx\@empty #1% attention, #1 could be bb.., bad if first after \ifx
+    \setbox\spx@image@box=\hbox{\py@Oldincludegraphics{#2}}%
+    \ifdim \wd\spx@image@box>\linewidth
+      \py@Oldincludegraphics[width=\linewidth]{#2}%
+    \else
+      \leavevmode\box\spx@image@box
+    \fi
+  \else
     \py@Oldincludegraphics[#1]{#2}%
-  \fi%
+  \fi
 }
+% Writer will put \sphinxincludegraphics in LaTeX source, and with this,
+% documents which used their own modified \includegraphics will compile
+% as before. But see warning above.
+\newcommand*{\sphinxincludegraphics}{\includegraphics}
 
 % to make pdf with correct encoded bookmarks in Japanese
 % this should precede the hyperref package

sphinx/writers/latex.py

@@ -411,7 +411,8 @@ class LaTeXTranslator(nodes.NodeVisitor):
             self.elements['date'] = format_date(builder.config.today_fmt or _('%b %d, %Y'),
                                                 language=builder.config.language)
         if builder.config.latex_logo:
-            self.elements['logo'] = '\\includegraphics{%s}\\par' % \
+            # no need for \\noindent here, used in flushright
+            self.elements['logo'] = '\\sphinxincludegraphics{%s}\\par' % \
                                     path.basename(builder.config.latex_logo)
         # setup babel
         self.babel = ExtBabel(builder.config.language)
@@ -1428,7 +1429,7 @@ class LaTeXTranslator(nodes.NodeVisitor):
             except KeyError:
                 pass
         if not is_inline:
-            pre.append('\n')
+            pre.append('\n\\noindent')
             post.append('\n')
         pre.reverse()
         if node['uri'] in self.builder.images:
@@ -1446,7 +1447,7 @@ class LaTeXTranslator(nodes.NodeVisitor):
         if include_graphics_options:
             options = '[%s]' % ','.join(include_graphics_options)
         base, ext = path.splitext(uri)
-        self.body.append('\\includegraphics%s{{%s}%s}' % (options, base, ext))
+        self.body.append('\\sphinxincludegraphics%s{{%s}%s}' % (options, base, ext))
         self.body.extend(post)
 
     def depart_image(self, node):
@@ -1472,7 +1473,7 @@ class LaTeXTranslator(nodes.NodeVisitor):
                 self.body.append('\\begin{sphinxfigure-in-table}\n\\centering\n')
             if any(isinstance(child, nodes.caption) for child in node):
                 self.body.append('\\capstart')
-            self.context.append(ids + '\\end{sphinxfigure-in-table}\n')
+            self.context.append(ids + '\\end{sphinxfigure-in-table}\\relax\n')
         elif node.get('align', '') in ('left', 'right'):
             if 'width' in node:
                 length = width_to_latex_length(node['width'])

tests/test_build_latex.py

@@ -113,21 +113,24 @@ def test_writer(app, status, warning):
     result = (app.outdir / 'SphinxTests.tex').text(encoding='utf8')
 
     assert ('\\begin{sphinxfigure-in-table}\n\\centering\n\\capstart\n'
-            '\\includegraphics{{img}.png}\n\\sphinxfigcaption'
-            '{figure in table}\\label{markup:id7}\\end{sphinxfigure-in-table}' in result)
+            '\\noindent\\sphinxincludegraphics{{img}.png}\n'
+            '\\sphinxfigcaption{figure in table}\\label{markup:id7}'
+            '\\end{sphinxfigure-in-table}\\relax' in result)
 
     assert ('\\begin{wrapfigure}{r}{0pt}\n\\centering\n'
-            '\\includegraphics{{rimg}.png}\n\\caption{figure with align option}'
-            '\\label{markup:id8}\\end{wrapfigure}' in result)
+            '\\noindent\\sphinxincludegraphics{{rimg}.png}\n'
+            '\\caption{figure with align option}\\label{markup:id8}'
+            '\\end{wrapfigure}' in result)
 
     assert ('\\begin{wrapfigure}{r}{0.500\\linewidth}\n\\centering\n'
-            '\\includegraphics{{rimg}.png}\n\\caption{figure with align \\& figwidth option}'
-            '\\label{markup:id9}\\end{wrapfigure}' in result)
+            '\\noindent\\sphinxincludegraphics{{rimg}.png}\n'
+            '\\caption{figure with align \\& figwidth option}\\label{markup:id9}'
+            '\\end{wrapfigure}' in result)
 
     assert ('\\begin{wrapfigure}{r}{3cm}\n\\centering\n'
-            '\\includegraphics[width=3cm]{{rimg}.png}\n'
-            '\\caption{figure with align \\& width option}'
-            '\\label{markup:id10}\\end{wrapfigure}' in result)
+            '\\noindent\\sphinxincludegraphics[width=3cm]{{rimg}.png}\n'
+            '\\caption{figure with align \\& width option}\\label{markup:id10}'
+            '\\end{wrapfigure}' in result)
 
 
 @with_app(buildername='latex', freshenv=True,  # use freshenv to check warnings
@@ -574,12 +577,12 @@ def test_image_in_section(app, status, warning):
     print(result)
     print(status.getvalue())
     print(warning.getvalue())
-    assert ('\chapter[Test section]'
-            '{\includegraphics[width=15pt,height=15pt]{{pic}.png} Test section}'
+    assert ('\\chapter[Test section]'
+            '{\\sphinxincludegraphics[width=15pt,height=15pt]{{pic}.png} Test section}'
             in result)
-    assert ('\chapter[Other {[}blah{]} section]{Other {[}blah{]} '
-            '\includegraphics[width=15pt,height=15pt]{{pic}.png} section}' in result)
-    assert ('\chapter{Another section}' in result)
+    assert ('\\chapter[Other {[}blah{]} section]{Other {[}blah{]} '
+            '\\sphinxincludegraphics[width=15pt,height=15pt]{{pic}.png} section}' in result)
+    assert ('\\chapter{Another section}' in result)
 
 
 @with_app(buildername='latex', confoverrides={'latex_logo': 'notfound.jpg'})