The auto-generated pages for a registered library are wonderful. It’s a great way to see code which illustrates features of a library, when exploring what there is out there.
But I sometimes would like to include a slightly more structured bit of documentation with each example, in particular a small screenshot when it’s about attached hardware.
So here’s an idea: for each example xyz.{c,cpp,ino,...) matched and shown on the library’s page, look for xyz.md (or even xyz.txt) as well, and if present, render it in front of the code block. That would allow adding just that extra per-example touch to make the default library page show a nice customisable intro.
On a related note: I’m not sure what the sorting order is for showing all the examples - it appears to be related to creation or modification dates. Is there a way to influence this, in particular to force a specific example to be shown first?
It’s not quite the same as a per-example readme. I’m currently writing a library and very much encouraged to write lots of little demo’s, because it’s so nice to see them all listed on the library page @ pio,org, and makes for a very quick intro to what the library is about (code says so much more than prose, IMO - but not everyone agrees with that, probably).
For the full library docs, I can already simply click on the Homepage and Repository links already present on each library’s page. I don’t think there’s a need to replicate that, but it’s really a matter of personal preference. GitHub’s automatic display of the README encourages writing a comprehensive top-level README, which could in fact be a disadvantage when also shown on pio.org (it would push all the examples down).
How about the following: show the full top-level README when landing on the page, but replace it with the example code when an example is selected from the buttons/drop-down.
Then we could have it all: a user-defined intro on the landing page, as well as an easy way to browse through all the examples. And then, I still think it would be nice to show per-example readme’s when present. Probably best before the code - or maybe after the code, but in that case I’d limit the size of the code window shown. Else you’d easily miss such a readme.
For an example, click on the waterfall.cpp example of the JeeH library, and compare with the README which I’d love to show as well, for that specific example.