[docs] Move README.md into lib docs and use cargo-readme to generate the README
virtualritz opened this issue · comments
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.
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?
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.
That doesn't mean you wouldn't keep the guide as-is ofc. The guide is very valuable for people new to the crate.
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?
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.
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