I have thought about this before. One problem is that not infrequently, an example would break the flow because you have to explain things in sufficient detail to have the example make sense. It might not break the flow for you the very first time you need the example, but then you have to scroll past it every single time thereafter.
It would improve this aspect of the documentation to be able to make use of the HTML5 summary-detail elements, but to do this properly would need support at the Sphinx and perhaps docutils levels. As far as I know, that support isn’t available, though you can simulate it in a theme as I’ve done here. With such support, examples would take up just one line by default when in an unexpanded state, and as much space as needed when actually expanded by someone who needs to refer to the example. Another approach would be to use HTML tooltips to show examples while hovering over an “example” icon or similar, but again that would need choosing a suitable browser-side tooltip framework, play nicely with third-party themes and other build targets (than HTML), etc.