refactor readme

[securelyfitz]

Previously considered refactoring the readme into separate readmes per interface, but have gotten lots of feedback on the 'flat' readme format, so will keep it.

I added a toc in 1e7971c (first generated with doctoc, but manually tweaked for brevity - it should be rather static so no need to automate updates)

Originally the 'usage' was supposed to be broken down by header, but became a list of protocols instead.
Then, the 'pinouts' was supposed to be a raw pinout list, but became a protocol specific list instead.

1. should probably merge the 'pinout' sections into the corresponding 'usage' sections
2. may still be worth adding a combined grand unified pinout map (though this might still be best under the LA heading)

[fharding1]

I'll add that I'm pro flat README 😁 I think the Table of Contents works great.

[hamid-elaosta]

Just to add an extra opinion.

I found it relatively simple to convert the single README to an ebook as a little reference for on my e-Reader, only needed minor post-processing to fix the code blocks and add a ToC using Calibre, the "#" headers become chapters and sections etc.

Relative image URLs would help a bit too but not a big deal.

[colinoflynn]

Love the flat README - as is it's pretty brief on each topic I think, so still hitting the README feel. If you start adding multiple examples to each section could see what you mean about breaking it out.

If you want a bit of both, you can setup github actions that do fancier processing on doc commits. For example with https://github.com/newaetech/chipwhisperer-target-cw308t we have a GH action that copies all the README.md files in the individual subdirectory into another repo with different names & then builds the doc output with mkdocs to https://rtfm.newae.com . You could probably break out individual .md files if you wanted but still auto-merge them into one flat .md file for those who want a single file. But it's a lot more hassle than you've got now ;-)

[skochinsky]

I would love to have a downloadable, self-contained PDF or EPUB that can be viewed offline.

[fharding1]

I would love to have a downloadable, self-contained PDF or EPUB that can be viewed offline.

Pandoc is pretty good at converting markdown into a readable PDF/EPUB. I don't like the idea of keeping generated binary PDF/EPUB files in the repository, but perhaps this is something we could include in releases like we do with the schematic PDFs.

[securelyfitz]

Agree with @fharding1, i like including a pdf/epub in the release bundles. We're overdue to release the v1.1 bundle, but i have a few readme more additions i should include before we roll that.