Fix inclusion of random.js in HTML output (#6935)

* Revert removal of random gallery script

This script was removed in #6933 [1] even though it is still in use on our
front page [2]! Therefore revert this particular change of #6933.

[1] #6933
[2] scikit-image/skimage-web#85

* Merge random.js generation into sphinx_extensions.py

Previously, `gallery_random.py` would generate the appropriate
`random.js` file with the `source/_static` as the target folder after
Sphinx itself was done. However, this meant that `random.js` would not
be included in our CI's build artifacts (locally it's included if
sphinx is run a second time).

Inclusion in skimage_extensions.py with a trigger on the Sphinx event
"build-finished" ensures that the appropriate output path can be
determined from Sphinx's configuration.

This inclusion seems to have been broken at least since 2020-08-15 [2].

[2] http://web.archive.org/web/20200815074104/https://scikit-image.org/

doc/ext/skimage_extensions.py

@@ -1,10 +1,18 @@
-"""Custom Sphinx extensions for scikit-image's docs."""
+"""Custom Sphinx extensions for scikit-image's docs.
+
+Have a look at the `setup` function to see what kind of functionality is added.
+"""
 
 import re
+from pathlib import Path
 
+from sphinx.util import logging
 from sphinx.directives.other import TocTree
 
 
+logger = logging.getLogger(__name__)
+
+
 def natural_sort_key(item):
     """Transform entries into tuples that can be sorted in natural order [1]_.
 
@@ -55,5 +63,74 @@ def parse_content(self, toctree):
         return ret
 
 
+RANDOM_JS_TEMPLATE = '''\
+
+   function insert_gallery() {
+       var images = {{IMAGES}};
+       var links = {{LINKS}};
+
+       ix = Math.floor(Math.random() * images.length);
+       document.write(
+'{{GALLERY_DIV}}'.replace('IMG', images[ix]).replace('URL', links[ix])
+       );
+
+       console.log('{{GALLERY_DIV}}'.replace('IMG', images[ix]).replace('URL', links[ix]));
+   };
+
+'''
+
+
+GALLERY_DIV = '''\
+<div class="gallery_image">
+      <a href="URL"><img src="IMG"/></a>
+</div>\
+'''
+
+
+def write_random_js(app, exception):
+    """Generate a javascript snippet that links to a random gallery example."""
+    if app.builder.format != "html":
+        logger.debug(
+            "[skimage_extensions] skipping generation of random.js for non-html build"
+        )
+        return
+
+    build_dir = Path(app.outdir)
+    random_js_path = Path(app.outdir) / "_static/random.js"
+
+    image_urls = []
+    tutorial_urls = []
+    url_root = "https://scikit-image.org/docs/dev/"
+    examples = build_dir.rglob("auto_examples/**/plot_*.html")
+    for example in examples:
+        image_name = f"sphx_glr_{example.stem}_001.png"
+        if not (build_dir / "_images" / image_name).exists():
+            continue
+        image_url = f'{url_root}_images/{image_name}'
+        tutorial_url = f'{url_root}_{example.relative_to(build_dir)}'
+        image_urls.append(image_url)
+        tutorial_urls.append(tutorial_url)
+
+    if tutorial_urls == 0:
+        logger.error(
+            "[skimage_extensions] did not find any gallery examples while creating %s",
+            random_js_path
+        )
+        return
+
+    content = RANDOM_JS_TEMPLATE.replace('{{IMAGES}}', str(image_urls))
+    content = content.replace('{{LINKS}}', str(tutorial_urls))
+    content = content.replace('{{GALLERY_DIV}}', ''.join(GALLERY_DIV.split('\n')))
+
+    with open(random_js_path, 'w') as file:
+        file.write(content)
+    logger.info(
+        "[skimage_extensions] created %s with %i possible targets",
+        random_js_path,
+        len(tutorial_urls),
+    )
+
+
 def setup(app):
     app.add_directive('naturalsortedtoctree', NaturalSortedTocTree)
+    app.connect('build-finished', write_random_js)