[DOC] Add automated mini-gallery examples for API pages

[Kaustbh]

This PR adds a custom Sphinx extension that automatically displays mini-gallery example cards on all API reference pages. When users visit documentation for any class or function, they see a grid of notebook examples that demonstrate that object.

Reference Issues/PRs

Fixes #164

What does this implement/fix? Explain your changes.

Does your contribution introduce a new dependency? If yes, which one?

Any other comments?

PR checklist

For all contributions

• I've added myself to the list of contributors. Alternatively, you can use the @all-contributors bot to do this for you after the PR has been merged.
• [DOC ] The PR title starts with either [ENH], [MNT], [DOC], [BUG], [REF], [DEP] or [GOV] indicating whether the PR topic is related to enhancement, maintenance, documentation, bugs, refactoring, deprecation or governance.

For new estimators and functions

• I've added the estimator/function to the online API documentation.
• (OPTIONAL) I've added myself as a __maintainer__ at the top of relevant files and want to be contacted regarding its maintenance. Unmaintained files may be removed. This is for the full file, and you should not add yourself if you are just making minor changes or do not want to help maintain its contents.

For developers with write access

• (OPTIONAL) I've updated aeon's CODEOWNERS to receive notifications about future changes to these files.

[aeon-actions-bot]

Thank you for contributing to aeon

I did not find any labels to add based on the title. Please add the [ENH], [MNT], [BUG], [DOC], [REF], [DEP] and/or [GOV] tags to your pull requests titles. For now you can add the labels manually.

The Checks tab will show the status of our automated tests. You can click on individual test runs in the tab or "Details" in the panel below to see more information if there is a failure.

If our pre-commit code quality check fails, any trivial fixes will automatically be pushed to your PR unless it is a draft.

Don't hesitate to ask questions on the aeon Discord channel if you have any.

PR CI actions

These checkboxes will add labels to enable/disable CI functionality for this PR. This may not take effect immediately, and a new commit may be required to run the new configuration.

• Run pre-commit checks for all files
• Run mypy typecheck tests
• Run all pytest tests and configurations
• Run all notebook example tests
• Run numba-disabled codecov tests
• Stop automatic pre-commit fixes (always disabled for drafts)
• Disable numba cache loading
• Regenerate expected results for testing
• Push an empty commit to re-run CI checks

[TonyBagnall]

Thanks for the PR. This looks like a useful feature, and the core structure seems sensible. The main thing I wanted to ask about is how notebooks are matched to classes and estimators. Could you explain that part a bit more? For example, I would expect classifiers to link to the classification notebook, and I was not clear whether the current matching guarantees that.

[Kaustbh]

During the documentation build, each example notebook is analyzed using Python’s Abstract Syntax Tree (AST) module. Instead of executing the notebooks, the AST parser inspects the code cells and identifies which aeon classes or functions are actually used in the code (not just imported). Based on this analysis, the system constructs a mapping that links each aeon object to the example notebooks in which it appears.

For thumbnails, instead of trying to infer image names automatically, the system reads the examples.md file. This file already contains curated example entries along with their associated images. By parsing this file, we build a second mapping that connects each example notebook to the image used as its thumbnail.

Both of these mappings—the object-to-example mapping and the example-to-thumbnail mapping—are stored temporarily inside the Sphinx build environment. This allows them to be accessed during the documentation build when the pages are being generated.

Later, when the documentation pages are rendered, the custom mini-gallery directive is encountered on an API page. At that point, the directive retrieves the mappings from the Sphinx environment, determines which example notebooks correspond to the API object being documented, and generates the gallery cards with the correct thumbnails and links to the example pages.

Importantly, this mapping is only needed during the build process. The gallery HTML is generated at build time and written directly into the final documentation pages. Once the build is complete, the mappings themselves are no longer required, because the resulting HTML pages already contain the rendered gallery with the example links and images. When a user later opens an API page in the browser, it simply displays the pre-generated HTML content rather than recomputing the mappings.

For example, I would expect classifiers to link to the classification notebook

To clarify, we are not linking classes based on their category (like "classifiers go to classification notebooks"). Instead, the matching is based entirely on actual usage.
If a class like Catch22Classifier is imported and used in any notebook whether it is in classification, transformations, or benchmarking it will appear in the gallery on that class's API page.

[TonyBagnall]

Thanks, the overall approach makes sense and your explanation of the AST-based matching was helpful.

I have a question. At the moment the directive matches examples using only the short object name and takes the first key.endswith(f".{object_name}") hit. Since the templates pass only {{ objname }}, this looks ambiguous for any duplicate class or function names across modules, which we try avoid but is possible. Could you change this to use the fully qualified name instead, for example by passing module + objname from the template and matching exactly?

Also, the gallery section is created before thumbnails are filtered, so pages could end up with an empty “Gallery Examples” heading if matched notebooks are missing thumbnail entries. It would be good to skip the section entirely in that case.

One minor cleanup point: aeon_gallery.css seems to be added both in setup() and in html_css_files, so only one of those should be needed.

[MatthewMiddlehurst]

Hi, thanks for the PR. This is a very useful addition to the documentation, and from what I can see it generates what we want. We may want to move it up further so it is not at the bottom of the page, but not for this PR.

My main concern is whether we need some of this, and if adding our own sphinx extension will add additional maintenance when we have to update versions.

From previous discussion the main issue is that sphinx-gallery does not like .ipynb files, and only takes .py files. It seems like it would be a lot simpler to just convert our notebooks to .py files when building the documentation, then use those. e.g. using jupyter nbconvert --to script 'my-notebook.ipynb' or similar (not verified if that would work!).

Is there anything this PR is doing that we wouldn't get from the above, or would the above be more complex in practice?

Fine with this approach over nothing, but feel we should consider a simpler alternative if it is possible.

[Kaustbh]

Hello Matthew, I explored the notebook to script conversion approach using both nbconvert and jupytext.

I ran into a few issues with the conversion step. The generated .py files are not fully reliable representations of the notebooks for example, embedded images are not preserved, some markdown structure is lost, and cross-references or links between notebooks don’t translate cleanly.

Another concern is that if we rely on sphinx-gallery in the standard way, it executes each script during the build to generate outputs. Some of our examples (e.g. deep learning classifiers) are relatively heavy and may require GPU support, which would significantly increase build time and introduce additional environment dependencies.

I also experimented with a hybrid approach: converting notebooks to scripts without execution and using sphinx-gallery only for object-to-example matching (i.e., backreferences for the mini-galleries), while continuing to use the existing notebook-rendered HTML pages for the actual examples. However, this also introduces complications, as sphinx-gallery backreference system is tightly coupled to its own generated pages, so linking cleanly to the existing HTML examples is not straightforward.

what approach would you recommend I proceed with from here?