Fix broken TOC of PDFs if section includes an image

If someone adds an image to a section it will be added to the sidebar
TOC of a PDF, too. A PDF viewer will show the "width and height"
data instead of an image. So we need to filter out images for this with
the optional "short title" of latex sections.

sphinx/writers/latex.py

@@ -25,6 +25,7 @@ from sphinx import highlighting
 from sphinx.errors import SphinxError
 from sphinx.locale import admonitionlabels, _
 from sphinx.util import split_into
+from sphinx.util.nodes import clean_astext
 from sphinx.util.osutil import ustrftime
 from sphinx.util.texescape import tex_escape_map, tex_replace_map
 from sphinx.util.smartypants import educate_quotes_latex
@@ -717,11 +718,15 @@ class LaTeXTranslator(nodes.NodeVisitor):
             self.this_is_the_title = 0
             raise nodes.SkipNode
         elif isinstance(parent, nodes.section):
+            short = ''
+            if node.traverse(nodes.image):
+                short = '[%s]' % ' '.join(clean_astext(node).split()).translate(tex_escape_map)
+
             try:
-                self.body.append(r'\%s{' % self.sectionnames[self.sectionlevel])
+                self.body.append(r'\%s%s{' % (self.sectionnames[self.sectionlevel], short))
             except IndexError:
                 # just use "subparagraph", it's not numbered anyway
-                self.body.append(r'\%s{' % self.sectionnames[-1])
+                self.body.append(r'\%s%s{' % (self.sectionnames[-1], short))
             self.context.append('}\n')
 
             self.restrict_footnote(node)

tests/roots/test-image-in-section/conf.py

@@ -0,0 +1,11 @@
+# -*- coding: utf-8 -*-
+
+master_doc = 'index'
+
+rst_epilog = '''
+.. |picture| image:: pic.png
+    :width: 15pt
+    :height: 15pt
+    :alt: alternative_text
+'''
+

tests/roots/test-image-in-section/index.rst

@@ -0,0 +1,18 @@
+test-image-in-section
+=====================
+this is dummy content
+
+
+|picture| Test section
+----------------------
+blah blah blah
+
+
+Another section
+---------------
+another blah
+
+
+Other [blah] |picture| section
+------------------------------
+other blah

tests/test_build_latex.py

@@ -423,6 +423,19 @@ def test_latex_show_urls_is_no(app, status, warning):
             '{sphinx-dev@googlegroups.com}\n' in result)
 
 
+@with_app(buildername='latex', testroot='image-in-section')
+def test_image_in_section(app, status, warning):
+    app.builder.build_all()
+    result = (app.outdir / 'Python.tex').text(encoding='utf8')
+    print(result)
+    print(status.getvalue())
+    print(warning.getvalue())
+    assert ('\chapter[Test section]{\includegraphics[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)
+
+
 @with_app(buildername='latex', confoverrides={'latex_logo': 'notfound.jpg'})
 def test_latex_logo_if_not_found(app, status, warning):
     try: