Add examples where this function is used in docs

[chaithyagr]

We currently have a lot of examples that it could be hard to know an example exists which calls a specific function of interest.
It could help a lot to add links to examples where a particular function is used. This should be automatic, as I see it in matplolib and scikit learn.

ChatGPT gave this:

import os
import glob

# Enable required Sphinx extensions
extensions = [
    "sphinx.ext.autodoc",
    "sphinx.ext.napoleon",
    "sphinx.ext.linkcode",  # Enables linking to external sources
]

EXAMPLES_DIR = "examples"  # Path where your example scripts are stored

def find_examples(func_name):
    """Search example scripts for function usage."""
    examples = []
    for file in glob.glob(os.path.join(EXAMPLES_DIR, "*.py")):
        with open(file, "r") as f:
            content = f.read()
            if func_name in content:
                # Convert file path to a Sphinx doc reference
                doc_link = f":doc:`{file.replace('.py', '')}`"
                examples.append(doc_link)
    return examples

def link_examples(app, what, name, obj, options, lines):
    """Automatically inject example references in docstrings."""
    examples = find_examples(name)
    if examples:
        lines.append("\n**Examples:**")
        lines.extend(["- " + e for e in examples])

def setup(app):
    app.connect("autodoc-process-docstring", link_examples)

[paquiteau]

Sphinx Gallery has everything already:)

https://sphinx-gallery.github.io/stable/configuration.html#references-to-examples

[chaithyagr]

Wonderful, it could also help to have forward references to API in examples. I think this is fairly easy, just that we should not linik it to numpy or scipy docs which will lead to a lot of confusion in links.

[Daval-G]

For trajectories I was planning to move all initializations into files by groups. I can add references to examples at this occasion, a few at a time

[chaithyagr]

Nah, i think it should be automatic, don't waste your time manually doing it. I think as @paquiteau mentioned we should be able to do it easily