Skip to content

DOC: Enable Sphinx-Gallery example recommender#13867

Open
kidusabe1 wants to merge 1 commit intomne-tools:mainfrom
kidusabe1:enable-sg-recommender
Open

DOC: Enable Sphinx-Gallery example recommender#13867
kidusabe1 wants to merge 1 commit intomne-tools:mainfrom
kidusabe1:enable-sg-recommender

Conversation

@kidusabe1
Copy link
Copy Markdown

Reference issue (if any)

Fixes #13864.

What does this implement/fix?

Enables the Sphinx-Gallery example recommender by adding "recommender": {"enable": True} to sphinx_gallery_conf in doc/conf.py. Each gallery page will gain a "Related examples" block at the bottom, computed via TF-IDF over example source text.

Additional information

  • I verified against sphinx-gallery==0.21.0 that recommender is a valid sphinx_gallery_conf key and that {"enable": True} is sufficient — SG falls back to ExampleRecommender defaults (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.
  • No dependency changes required: scikit-learn (the recommender's only extra dependency) is already in the doc group, and numpy is a core dep. I also checked that the new config passes sphinx.config.is_serializable, which is asserted at doc/conf.py:574.
  • I didn't attempt a local full doc build for this change (config-only, and the full build needs the sample data + sphinx env). Could a reviewer please confirm the CircleCI doc artifact shows a "Related examples" section at the bottom of a gallery page? Happy to adjust parameters if output looks off on smaller subsections.
  • First-time contributor — added name to doc/changes/names.inc and used :newcontrib: in the changelog fragment per the contributing guide.

Copilot AI review requested due to automatic review settings April 24, 2026 18:21
Copy link
Copy Markdown

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Comment thread doc/conf.py
),
"copyfile_regex": r".*index\.rst", # allow custom index.rst files
"parallel": sphinx_gallery_parallel,
"recommender": {"enable": True},
Copy link

Copilot AI Apr 24, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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).

Copilot uses AI. Check for mistakes.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

consider using SG example recommender

2 participants