Using only the backlinks feature in existing RST prose

Hi!

Firstly, thanks for the seemingly great package 😄 I see lots of successful libraries are using it to a great effect. And I intend to be your next user, especially once I write a bunch of python examples. For now though, I’d like to only use the awesome backlink feature to enhance my examples that are written inside existing RST prose.

Essentially, what I’m after is being able to write ordinary Sphinx RST like

Document
========
This is a document with the following example:

.. code:: python

    import lib

    lib.foo()
    b = lib.Bar()
    b.meth()

and have the links be generated regardless of the file’s location. It’s not obvious whether or not this is even possible since the documentation is so focused on the example gallery (which is hardly surprising 😅), but I suspect it is some combination of backreferences_dir, doc_module and reference_url as laid out in the few tutorials starting here. How could this be achieved?

Apologies for essentially asking the library to do something that it wasn’t necessarily supposed to do. So feel free to shut this down if you already know it won’t be possible. But I’m over the moon that this is even a thing! Keep making documentation great ❤️

---

Eventually having mini-galleries or just plain lists of example locations in reference documentation would be great too, but I think that’s too much for one user support question 😅 I might still be misunderstanding the features altogether.

[felix-hilden]

I’ve recently implemented the functionality in a new Sphinx extension sphinx-codeautolink. As I said, the approach was different enough to warrant a new project in my opinion. Execution is fine for your gallery and actually should work much better in certain situations to determine references. But I went for static analysis instead for fewer assumptions and more flexibility. But I’d like to say thanks for the initial discussion! Your directions and source were very helpful when piecing together what should happen 👍 I’ll leave this open if you’d like to do something with it, or if you’d like to discuss something I’m all for it. But you can consider my use case satisfied.

[lucyleeow]

I think statically getting the backreferences is the tricky part. The tool should be able to work for code blocks regardless of whether the file it came from was .py or .rst -> i.e. it takes a code block and outputs backlined rst.

Whether we go from .py -> rST -> execute/get backreferences OR .py -> execute/get backreferences -> rST , would then be fairly trivial and a decision based on user need and backwards compatibility etc

You can take a look at [backreferences.py](https://github.com/sphinx-gallery/sphinx-gallery/blob/master/sphinx_gallery/backreferences.py) to get an idea of how it is done now.