Examples/Demos have become unmaintainable

[jonas-schievink]

We currently have 24 independent demo projects in the examples directory, each with its own Cargo.toml that needs to be maintained, some being of questionable didactic value or demonstrating functionality that is already incorporated in another demo. Many haven't been updated ever since they were added, except for fixing breakage. This is not maintainable.

I'm declaring a moratorium on adding more examples until we fix this.

I propose that we:

• Convert some (or even most) demos to doc examples, especially ones that are specific to a single peripheral
• Merge all of the remaining demos into the same Cargo package (demos) and make them actual Cargo examples

Other solutions welcome.

[therealprof]

Convert some (or even most) demos to doc examples, especially ones that are specific to a single peripheral

I haven't really seen any convincing embedded doc examples yet. They also tend to bitrot very quickly because even if they can be compiled and do compile, people tend to put important details into the commentary because you can't really code it out and that doesn't see any testing or updates.

Also the important part is being able to transfer doc examples back into real projects and is often a big stumbling block, even if the doc example is actually good.

Merge all of the remaining demos into the same Cargo package (demos) and make them actual Cargo examples

My two cents: In stm32f4xx-hal we're thinking about going the opposite route and moving Cargo examples into their one or more Cargo packages. If you have a single set of examples, not only the HAL impl itself but also all other dependencies (and their versions) are shared so you cannot simply bump one or add a new example without upgrading all others. The same goes for features so if you'd like to make aspects of the examples configurable you'll have to do the feature disambiguation yourself and also the Cargo.toml does get a bit unwieldy.

Maybe there's some middle ground?