Crates io suggestion .. #[demo] , render examples?


Imagine if there was a convention for providing ‘demo programs’ /‘examples’

  • the outputs are rendered into thumbnails , browsable on the site,

  • a series of output formats would be recognised: plaintext, image, HTML, .OBJ …

  • possibly format the ‘demo’ as a transformation of data, e.g. register ‘input data’ aswell and have the opportunity for crate demos to be applied to the same input (although that in turn implies some greater setup). Crates are libraries, so maybe it’s not unfeasible to have this ‘demo’ as a standard stub that loads and feeds data expecting some output structure (e.g. a stub could be setup for a demo that transforms between 2 types of data , ‘image->image’, ‘plaintext -> OBJ’, whatever, and you could compare what different crates do with the same data)

  • Whilst this might seem focussed on graphical examples, what if there was an interesting way to generate flow charts/timelines or whatever visualizing the behaviour of more abstract processes

  • these are complementary to any documentation or ‘how to use it’ examples; they wouldn’t show source code, rather an indication of what it does.

I would see this as a more engaging way for people to discover potentially useful crates; although it might seem graphically focussed, I’m sure you could make an interesting visualisation for other types of intermediate data.

I was thinking I might try and do something like this for a bunch pieces of helper code that I was considering publishing i.e. organised ‘debug rendering’, but it struck me the idea might be more universal, or already considered.

I guess any crate can show URLs /images in it’s page, but the real point here is the initial browsing experience for the whole site, i.e. turning it from a ‘list of names’ to ‘a grid of images’.
“don’t tell me what it does… show me what it does” … a contrasting form of presentation


Cargo supports examples already, and can render images from the readme. You could combine the two to create a gallery on your crate’s page.


ok so imagine itself doing that combining, and rendering a gallery to browse… extra discoverability for crates that demonstrate what they do; “your crates page” is something only seen once someone already decided to look at it , rather than something seen in general browsing .