This idea was discussed at the coordination meeting, and I did some experimental work at https://github.com/eteq/sphinx-example-docs-testing , but I don't think we wrote it down in an issue somewhere...

The idea here is to replace the example gallery currently in the astropy docs with a plugin that finds marked examples from the docs and builds a list of examples from them. An additional stretch goal is to then also generate a gallery from any plots/images inside the examples. So this issue is about making that plugin (which is necessary before the content can be moved from the existing example gallery).

Two questions that need answering:

• What's the best way to indicate "this is an example"? The prototype work suggests the best thing is to just use a standard sphinx link, but with a standard prefix (i.e. .. _example-my-reference-label:). That's relatively easy to implement vs a dedicated sphinx directive or something like that.
• For @astrofrog : it may be we want to move this issue to one of the separate sphinx-related repos? Not sure which is the right place for it, though... Any thoughts? Or does it deserve its own separate repo?