use sphinx gallery for the usage examples

[12rambau]

This is the most advanced sphinx interface to build gallery of example and is used by many other tools in the ecosystem like pandas, cartopy and matplotlib.

https://sphinx-gallery.github.io/stable/index.html

[fitoprincipe]

BTW, can we avoid running the docs job when pushing into a PR? What about a pre-merge job? since I am not expert in this field, I asked copilot: https://copilot.microsoft.com/shares/DLriSitqEwGX6wzquUsPS

[12rambau]

I made it part of the PR CI to maintain documentation buildability (as we all tend to consider documentation as low tier importance), IMHO it is a feature more than a problem. What is the issue you face with the doc build ? (and note that I tried my best to make it available in readthedocs but I'm blocked by this issue: readthedocs/readthedocs.org#11755