Polkadot umbrella crate needs a README

[ggwpez]

No readme https://crates.io/crates/polkadot-sdk 😭

Should explain:

• what it is
• how it is supposed to be used (with small example)
• tips to get the most out of it
• versioning schema
• should look somewhat nice ✨

[kianenigma]

A better example:

https://crates.io/crates/polkadot-sdk-frame (README is bad, but this is better: https://docs.rs/polkadot-sdk-frame/0.8.0/polkadot_sdk_frame/)

We can use docify_readme to have a synchronized lib.rs and README. @iulianbarbu has experience with this, if need be whoever takes this on, can get some pointers from him.

Next, @ggwpez can you please link a few follow-up features that are needed in the umbrella-crate, seeding the way to have a roadmap for it? like #5934

Former doc about this, which maybe we can remove if no need for it anymore:

https://paritytech.github.io/polkadot-sdk/master/polkadot_sdk_docs/reference_docs/umbrella_crate/index.html

[huntbounty]

I’d be happy to help out if that’s okay! 😊

I think I get the motive of syncing the README with doc comments, and I know Rust has something like #![doc = include_str!("../README.md")] for that. But it sounds like you’re looking for something more sophisticated? Any pointers on you're referring to? @iulianbarbu @kianenigma

If it’s still along the lines of "embedding README into the doc comments" regardless, I’d be glad to start working on the README! 💕

[huntbounty]

Trying to reuse what’s still relevant from https://paritytech.github.io/polkadot-sdk/master/polkadot_sdk_docs/reference_docs/umbrella_crate/index.html. I’m a bit confused about the 'Known Issues' section—isn’t it expected behavior that imports aren’t inherited by inner modules? Or am I misunderstanding something here?

[ggwpez]

I’m a bit confused about the 'Known Issues' section—isn’t it expected behavior that imports aren’t inherited by inner modules?

Yea but not sure how many devs keep it in mind. Just wanted to point it out.

I think I get the motive of syncing the README with doc comments, and I know Rust has something like #![doc = include_str!("../README.md")] for that. But it sounds like you’re looking for something more sophisticated?

Not sure what we finally settles on; @kianenigma rather README.md and then include_str or writing rust docs directly and then exporting the README?

I dont really mind either, there just should be a README and it should stay up-to-date somehow with the Rust docs.