[docs] Move README.md into lib docs and use cargo-readme to generate the README

[virtualritz]

I would do this and open a PR, if you're ok with that.

I think it would also be great to split the info in the guide up for the docs and put a copy of the resp. part under each function/struct it pertains to.

The guide is great for a start but I find myself frequently not having bits and bobs of it in the docs and then having to jump back and forth.

[johannesvollmer]

Ah yes nice.

The guide is meant for overview, so it would be nice to keep information about the relationship between types. If something is only important for a single type, it should definitely be moved to the type documentation :)

Can you give an example how exactly you would split it up?

[virtualritz]

Can you give an example how exactly you would split it up?

I would copy the guide's Reading an Image->Layer section under a Layer struct docs Reading section and the Writing an Image->Layer section under a Layer struct docs Writing section.

And the same for all the other structs the guide has details on.

I also thought about opening a ticket with cargo-readme and ask for a feature that allows deriving a GUIDE.md or even a MD book from extracting all the information found in inline docs.

I think this is very feasible. If you write good docs with examples they are almost like a guide, just finicky to navigate/understand for a first time user.
E.g. I though about writing a guide for my nsi crate and mostly this would just be copypasta of inline docs I already wrote.

[virtualritz]

That doesn't mean you wouldn't keep the guide as-is ofc. The guide is very valuable for people new to the crate.

[johannesvollmer]

I also thought about opening a ticket with cargo-readme and ask for a feature that allows deriving a GUIDE.md or even a MD book from extracting all the information found in inline docs.

This sounds interesting. The duplication of information was my main pain point in the previous discussion. Deriving the Guide or a Book from the docs would be wonderful. How does it work? Will it simply append the docs from multiple types, or is it more complex?

[virtualritz]

Haven't thought about it much. Afaik cargo-readme allows for templates. I was thinking that you have a section in the docs for each type/method/whatever and you may want to include that section in a guide at a specific place.

Possibly in the start of a section about that type/method/whatever. This also forces you to write the docs in a way that the text is suitable for a guide which is good practice, IMHO.

[johannesvollmer]

Sounds good. It will be worth the effort. Would you have a look and try to assemble a prototype?

One wish: Please try to keep the root directory as small as possible, try to put everything into a subfolder