Repository: sphinx-gallery/sphinx-gallery

Issue:
ENH More informative 'alt' attribute for thumbnails in index
Following from #663, make the alternative text ('alt' attribute of image in rst) for thumbnail images in the index.rst of generated galleries to be the title of the example file.

cc @ogrisel 

Discussion:
lucyleeow: @larsoner I don't understand the cause of the test failures. I seems that `test_junit` and `test_rebuild` are failing during setup but I don't understand why. tinybuild builds fine when I check.
The error is
```
ValueError: not enough values to unpack (expected 3, got 2)
```
but there all 3 output variables (intro, title, cost) are present.
larsoner: https://github.com/sphinx-gallery/sphinx-gallery/pull/668/files#diff-0cc5ccb98f5854a18c184ad4644a3509R759

beware the multiple `return` code path...

Patch:
diff --git a/doc/configuration.rst b/doc/configuration.rst
index 023f287..d826e7c 100644
--- a/doc/configuration.rst
+++ b/doc/configuration.rst
@@ -823,7 +823,7 @@ your ``Makefile`` with:
 .. code-block:: Makefile
 
     html-noplot:
-        $(SPHINXBUILD) -D plot_gallery=0 -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
+        $(SPHINXBUILD) -D plot_gallery=0 -b html $(ALLSPHINXOPTS) $(SOURCEDIR) $(BUILDDIR)/html
         @echo
         @echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
 
diff --git a/sphinx_gallery/backreferences.py b/sphinx_gallery/backreferences.py
index ee10a78..d2e6547 100644
--- a/sphinx_gallery/backreferences.py
+++ b/sphinx_gallery/backreferences.py
@@ -240,6 +240,7 @@ THUMBNAIL_TEMPLATE = """
 .. only:: html
 
  .. figure:: /{thumbnail}
+     :alt: {title}
 
      :ref:`sphx_glr_{ref_name}`
 
@@ -255,8 +256,8 @@ BACKREF_THUMBNAIL_TEMPLATE = THUMBNAIL_TEMPLATE + """
 """
 
 
-def _thumbnail_div(target_dir, src_dir, fname, snippet, is_backref=False,
-                   check=True):
+def _thumbnail_div(target_dir, src_dir, fname, snippet, title,
+                   is_backref=False, check=True):
     """Generate RST to place a thumbnail in a gallery."""
     thumb, _ = _find_image_ext(
         os.path.join(target_dir, 'images', 'thumb',
@@ -275,11 +276,11 @@ def _thumbnail_div(target_dir, src_dir, fname, snippet, is_backref=False,
 
     template = BACKREF_THUMBNAIL_TEMPLATE if is_backref else THUMBNAIL_TEMPLATE
     return template.format(snippet=escape(snippet),
-                           thumbnail=thumb, ref_name=ref_name)
+                           thumbnail=thumb, title=title, ref_name=ref_name)
 
 
 def _write_backreferences(backrefs, seen_backrefs, gallery_conf,
-                          target_dir, fname, snippet):
+                          target_dir, fname, snippet, title):
     """Write backreference file including a thumbnail list of examples."""
     if gallery_conf['backreferences_dir'] is None:
         return
@@ -296,7 +297,8 @@ def _write_backreferences(backrefs, seen_backrefs, gallery_conf,
                 ex_file.write('\n\n' + heading + '\n')
                 ex_file.write('^' * len(heading) + '\n')
             ex_file.write(_thumbnail_div(target_dir, gallery_conf['src_dir'],
-                                         fname, snippet, is_backref=True))
+                                         fname, snippet, title,
+                                         is_backref=True))
             seen_backrefs.add(backref)
 
 
diff --git a/sphinx_gallery/gen_rst.py b/sphinx_gallery/gen_rst.py
index eab8b4a..01fffc5 100644
--- a/sphinx_gallery/gen_rst.py
+++ b/sphinx_gallery/gen_rst.py
@@ -336,12 +336,12 @@ def generate_dir_rst(src_dir, target_dir, gallery_conf, seen_backrefs):
         'generating gallery for %s... ' % build_target_dir,
         length=len(sorted_listdir))
     for fname in iterator:
-        intro, cost = generate_file_rst(
+        intro, title, cost = generate_file_rst(
             fname, target_dir, src_dir, gallery_conf, seen_backrefs)
         src_file = os.path.normpath(os.path.join(src_dir, fname))
         costs.append((cost, src_file))
         this_entry = _thumbnail_div(target_dir, gallery_conf['src_dir'],
-                                    fname, intro) + """
+                                    fname, intro, title) + """
 
 .. toctree::
    :hidden:
@@ -756,7 +756,7 @@ def generate_file_rst(fname, target_dir, src_dir, gallery_conf,
     if md5sum_is_current(target_file):
         if executable:
             gallery_conf['stale_examples'].append(target_file)
-        return intro, (0, 0)
+        return intro, title, (0, 0)
 
     image_dir = os.path.join(target_dir, 'images')
     if not os.path.exists(image_dir):
@@ -818,9 +818,9 @@ def generate_file_rst(fname, target_dir, src_dir, gallery_conf,
                    if cobj['module'].startswith(gallery_conf['doc_module']))
     # Write backreferences
     _write_backreferences(backrefs, seen_backrefs, gallery_conf, target_dir,
-                          fname, intro)
+                          fname, intro, title)
 
-    return intro, (time_elapsed, memory_used)
+    return intro, title, (time_elapsed, memory_used)
 
 
 def rst_blocks(script_blocks, output_blocks, file_conf, gallery_conf):


Test patch:
diff --git a/sphinx_gallery/tests/test_backreferences.py b/sphinx_gallery/tests/test_backreferences.py
index 76a1e19..1eb1630 100644
--- a/sphinx_gallery/tests/test_backreferences.py
+++ b/sphinx_gallery/tests/test_backreferences.py
@@ -20,6 +20,7 @@ REFERENCE = r"""
 .. only:: html
 
  .. figure:: /fake_dir/images/thumb/sphx_glr_test_file_thumb.png
+     :alt: test title
 
      :ref:`sphx_glr_fake_dir_test_file.py`
 
@@ -46,10 +47,12 @@ def test_thumbnail_div(content, tooltip, is_backref):
     """Test if the thumbnail div generates the correct string."""
     with pytest.raises(RuntimeError, match='internal sphinx-gallery thumb'):
         html_div = sg._thumbnail_div('fake_dir', '', 'test_file.py',
-                                     '<"test">')
+                                     '<"test">', '<"title">')
     content = _sanitize_rst(content)
+    title = 'test title'
     html_div = sg._thumbnail_div('fake_dir', '', 'test_file.py',
-                                 content, is_backref=is_backref, check=False)
+                                 content, title, is_backref=is_backref,
+                                 check=False)
     if is_backref:
         extra = """
 
diff --git a/sphinx_gallery/tests/test_full.py b/sphinx_gallery/tests/test_full.py
index e6cb36e..528ba65 100644
--- a/sphinx_gallery/tests/test_full.py
+++ b/sphinx_gallery/tests/test_full.py
@@ -552,21 +552,51 @@ def test_rebuild(tmpdir_factory, sphinx_app):
                        different=('plot_numpy_matplotlib.ipynb'))
 
 
-def test_alt_text(sphinx_app):
-    """Test alt text"""
+def test_alt_text_image(sphinx_app):
+    """Test alt text for matplotlib images in html and rst"""
+    out_dir = sphinx_app.outdir
     src_dir = sphinx_app.srcdir
-    fname = op.join(src_dir, 'auto_examples', 'plot_matplotlib_alt.rst')
-    assert op.isfile(fname)
-    with codecs.open(fname, 'r', 'utf-8') as fid:
+    # alt text is fig titles, rst
+    example_rst = op.join(src_dir, 'auto_examples', 'plot_matplotlib_alt.rst')
+    with codecs.open(example_rst, 'r', 'utf-8') as fid:
         rst = fid.read()
     # suptitle and axes titles
     assert ':alt: This is a sup title, subplot 1, subplot 2' in rst
     # multiple titles
     assert ':alt: Left Title, Center Title, Right Title' in rst
 
-    fname = op.join(src_dir, 'auto_examples', 'plot_numpy_matplotlib.rst')
-    assert op.isfile(fname)
-    with codecs.open(fname, 'r', 'utf-8') as fid:
+    # no fig title - alt text is file name, rst
+    example_rst = op.join(src_dir, 'auto_examples',
+                          'plot_numpy_matplotlib.rst')
+    with codecs.open(example_rst, 'r', 'utf-8') as fid:
+        rst = fid.read()
+    assert ':alt: plot numpy matplotlib' in rst
+    # html
+    example_html = op.join(out_dir, 'auto_examples',
+                           'plot_numpy_matplotlib.html')
+    with codecs.open(example_html, 'r', 'utf-8') as fid:
+        html = fid.read()
+    assert 'alt="plot numpy matplotlib"' in html
+
+
+def test_alt_text_thumbnail(sphinx_app):
+    """Test alt text for thumbnail in html and rst."""
+    out_dir = sphinx_app.outdir
+    src_dir = sphinx_app.srcdir
+    # check gallery index thumbnail, html
+    generated_examples_index = op.join(out_dir, 'auto_examples', 'index.html')
+    with codecs.open(generated_examples_index, 'r', 'utf-8') as fid:
+        html = fid.read()
+    assert 'alt="SVG graphics"' in html
+    # check backreferences thumbnail, html
+    backref_html = op.join(out_dir, 'gen_modules',
+                           'sphinx_gallery.backreferences.html')
+    with codecs.open(backref_html, 'r', 'utf-8') as fid:
+        html = fid.read()
+    assert 'alt="Link to other packages"' in html
+    # check gallery index thumbnail, rst
+    generated_examples_index = op.join(src_dir, 'auto_examples',
+                                       'index.rst')
+    with codecs.open(generated_examples_index, 'r', 'utf-8') as fid:
         rst = fid.read()
-    # file name when no fig title
-    assert 'plot numpy matplotlib' in rst
+    assert ':alt: Trivial module to provide a value for plot_numpy_matplotlib.py' in rst  # noqa: E501