FEA Add examples recommender system

sphinx_gallery/gen_gallery.py

@@ -20,6 +20,7 @@
 import os
 import pathlib
 from xml.sax.saxutils import quoteattr, escape
+from itertools import chain
 
 from sphinx.errors import ConfigError, ExtensionError
 import sphinx.util
@@ -40,6 +41,7 @@
 from .interactive_example import post_configure_jupyterlite_sphinx
 from .interactive_example import create_jupyterlite_contents
 from .directives import MiniGallery, ImageSg, imagesg_addnode
+from .recommender import ExampleRecommender, _write_recommendations
 
 _KNOWN_CSS = ('sg_gallery', 'sg_gallery-binder', 'sg_gallery-dataframe',
               'sg_gallery-rendered-html')
@@ -76,6 +78,7 @@ def __call__(self, gallery_conf, script_vars):
     'download_all_examples': True,
     'abort_on_example_error': False,
     'only_warn_on_example_error': False,
+    'recommend_n_examples': True,
     'failing_examples': {},
     'passing_examples': [],
     'stale_examples': [],  # ones that did not need to be run due to md5sum
@@ -616,6 +619,38 @@ def generate_gallery_rst(app):
                 gallery_conf, target_dir, subsection_costs
             )
 
+        # Build recommendation system
+        # TODO: rename variables
+        if gallery_conf["recommend_n_examples"]:
+            if gallery_conf["recommend_n_examples"] is True:
+                recommender = ExampleRecommender()
+            else:
+                n_examples = gallery_conf["recommend_n_examples"]
+                recommender = ExampleRecommender(n_examples=n_examples)
+
+            all_py_examples = []
+            directory_explore = [gallery_dir_abs_path] + subsecs
+            for subsection in directory_explore:
+                src_dir = os.path.join(gallery_dir_abs_path, subsection)
+                # get filenames
+                listdir = [
+                    fname for fname in os.listdir(src_dir) if fname.endswith(".py")
+                ]
+                # sort them to ensure that the input will always be in the same
+                # order when giving it to the `fit` of the recommender
+                sorted_listdir = sorted(
+                    listdir, key=gallery_conf["within_subsection_order"](src_dir)
+                )
+                fullpath = [
+                    os.path.join(src_dir, file_name) for file_name in sorted_listdir
+                ]
+                all_py_examples.append(fullpath)
+            all_py_examples = list(chain.from_iterable(all_py_examples))
+
+            recommender.fit(all_py_examples)
+            for fname in all_py_examples:
+                _write_recommendations(recommender, fname, gallery_conf)
+
         # generate toctree with subsections
         if gallery_conf["nested_sections"] is True:
             subsections_toctree = _format_toctree(

sphinx_gallery/gen_rst.py

@@ -177,6 +177,11 @@ def __exit__(self, type_, value, tb):
     <br />"""
 
 
+RECOMMENDATIONS_INCLUDE = """\n
+.. include:: {0}.recommendations
+"""
+
+
 def codestr2rst(codestr, lang='python', lineno=None):
     """Return reStructuredText code block from code string."""
     if lineno is not None:
@@ -1321,6 +1326,13 @@ def save_rst_example(example_rst, example_file, time_elapsed,
                                         binder_badge_rst,
                                         ref_fname,
                                         jupyterlite_rst)
+
+    if gallery_conf["recommend_n_examples"]:
+        recommendation_fname = example_fname.rsplit(".", maxsplit=1)[0].rsplit(
+            "/", maxsplit=1
+        )[-1]
+        example_rst += RECOMMENDATIONS_INCLUDE.format(recommendation_fname)
+
     if gallery_conf['show_signature']:
         example_rst += SPHX_GLR_SIG