DOC: Enable Sphinx-Gallery example recommender#13867
DOC: Enable Sphinx-Gallery example recommender#13867kidusabe1 wants to merge 1 commit intomne-tools:mainfrom
Conversation
There was a problem hiding this comment.
Pull request overview
Note
Copilot was unable to run its full agentic suite in this review.
Enables Sphinx-Gallery’s example recommender in the docs build so gallery pages show “Related examples” based on TF‑IDF similarity.
Changes:
- Turn on the Sphinx-Gallery recommender via
sphinx_gallery_conf. - Add contributor to
names.inc. - Add a changelog fragment announcing the doc enhancement.
Reviewed changes
Copilot reviewed 3 out of 3 changed files in this pull request and generated 1 comment.
| File | Description |
|---|---|
doc/conf.py |
Enables Sphinx-Gallery recommender in sphinx_gallery_conf. |
doc/changes/names.inc |
Adds the contributor’s name/link. |
doc/changes/dev/13867.other.rst |
Adds a changelog entry for the new “Related examples” feature. |
| ), | ||
| "copyfile_regex": r".*index\.rst", # allow custom index.rst files | ||
| "parallel": sphinx_gallery_parallel, | ||
| "recommender": {"enable": True}, |
There was a problem hiding this comment.
Enabling the Sphinx-Gallery recommender generally adds a hard runtime dependency on scikit-learn during doc builds and can noticeably increase gallery build time/memory (it needs to vectorize example sources). If this repo has any doc-build paths that don’t install the full doc extras, this can cause build failures. Consider enabling this conditionally (e.g., only when scikit-learn is importable, or behind an env var used by CI) and/or setting the recommender parameters explicitly to keep behavior stable across sphinx-gallery version changes (e.g., n_examples, min_df, max_df).
Reference issue (if any)
Fixes #13864.
What does this implement/fix?
Enables the Sphinx-Gallery example recommender by adding
"recommender": {"enable": True}tosphinx_gallery_confindoc/conf.py. Each gallery page will gain a "Related examples" block at the bottom, computed via TF-IDF over example source text.Additional information
sphinx-gallery==0.21.0thatrecommenderis a validsphinx_gallery_confkey and that{"enable": True}is sufficient — SG falls back toExampleRecommenderdefaults (n_examples=5,min_df=3,max_df=0.9), which match what sphinx-gallery's own tinybuild uses. Happy to pin values explicitly if preferred.scikit-learn(the recommender's only extra dependency) is already in thedocgroup, andnumpyis a core dep. I also checked that the new config passessphinx.config.is_serializable, which is asserted atdoc/conf.py:574.doc/changes/names.incand used:newcontrib:in the changelog fragment per the contributing guide.