image-rs
Restructure image buffers in Readme
Closes: #1182
We have since then tied the Pixel trait more closely to ImageBuffer in design, hence these sections should likely go together. Also mentions the recent color handling. The IO traits are somewhat secondary and not primarily aimed at most users. A remark that decoding can be hooked should be sufficient for sparking interest in finding out the concrete details of the trait in the documentation.
I think we should consider what information lands "above the fold" at the start of the readme. Right now that's the couple pointless sentences that "image is an image library", but they are followed by a short code sample showing what the library can do.
The next thing (which this PR places first) is the long table listing out all the image formats and with only a few exceptions saying that "yes we can encode and decode this format, and the feature flag is what you'd expect". Maybe we could just add default-features to the list of features, have the description list out all the formats, and then link to https://docs.rs/image/latest/image/codecs/index.html for the rest of the details?
I like that structure you sketch, I mainly moved the code examples because they were both just showing the IO part. So do they fit? It was not easy to think of a replacement that went beyond that.
I've also questioned if the Readme is really the right place for it. The generated documentation, with a dedicated how-to section, could be far more extensive and structured at the same time. For instance Pillow is very minimal, despite having vast docs beyond the API.
The question really is: who is the Readme aimed at? We serve it both as the landing page in crates.io and as the Github one, and maybe that's a little too much. At least myself, when I go find out what a crate can do, I almost instantly go over to docs.rs instead of crates.io. No readme can provide a depth of understanding of capabalities as the linked, searchable cargo doc output. Also specifically regarding the code examples they are stuck in a bind that we can't make use of docs's full formatting (i.e. hiding lines) and they are also not executable from that place but we're currently checking them for being executable. Involving Cursor was a solution to make them runnable without literring when running cargo test, but it's not really a mininmal beginner example. I'm not sure if adding no_run etc. interferes with Github's rendering.
The feature / format table is a very good fit for the Readme in that feature flags are harder to parse from the documentation.
Updated to reflect the already completed changes of consolidating the table and undoing the removal of the initial example (until I've come with a better criteria for deciding on the functionality to put there instead). But, I've taken out the ImageDecoder and ImageDecoderRect trait references. I don't think these are relevant for most immediate users and especially the latter is in talks of being hard deprecated. They don't really complete the API listing either as some other traits such as animations are missing. We could add them back once that is sufficiently rounded. The buffer list also omits FlatSamples and View for instance.