### Problem
Hi all! my first issue here, I has been using rust for more than 2/…3 years? something like that, from the start to rn the docs has been crucial, and I have noted a patter that hits today, and a lot harder when we want to start using rust, is that there is no easy and fast way to run examples.
I'll use some extra words on this issue, because there is a lot of issues and contexts that affects this case.
Examples!! that docs that allow us to get an idea of how works, I do not mean the examples in crates that shows a lot of code, the examples in docs that shows how things works like step by step, this docs allow us to start learning a new crate, while more complex the crate usually we need to play more with them, each feature, step by step.
The main issue is the dependencies and features required to run each example, if you copy/paste a example, and add the libs it says you need, you can face that the example does not works, there can be several reasons:
- The example needed custom features of some libs
- The version of the crate you added is different from the one the example was build
- The version of the dependencies of the example are different from the ones you added, at the same time, the dependencies of the examples does not need to be the same as the crate you want to learn
- more and more
This can be caused in part because Rust is too stable! while this is a powerful feature also implies when we go to other project, a external dependency could already make a breaking change, time passes, and things works, just some times examples doesn't.
There is other weird circumstances like you fall in the docs that is not the latest version of the crate, or you are working in a specific one which needs specific dependencies and features again.
Today, I have the skills to in any of this circumstances be able to reach the right dependencies and packages versions and features, but I will use time, and for new ppl this would be very very hard, and a entry barrier, actually happened to me in the past.
Lets clear this out, we can always say this could be handled by the user, because with enough experience and learning we could handle it, but then I realised something else on this process, examples should follow the logic of be "Self-contained", the idea of a example is also be able to pick and run it to see how it works.
So picking this point of view, what it lacks the docs to reach this? The examples does not include the current crate, dependencies features and versions which was used to test them!
We could also go and start checking the dev section of the dependencies, but at least to me, is not expected to need information out of the example to be able to run an example, this leads us again to them be "self-contained".
### Proposed Solution
I think would be great, when we build the docs for HTML page, each example have a small tab, to show the package versions and features needed to run them, could also be a block of ``Cargo.toml`` the dep one to just copy paste.
This little change, even if duplicate a lot some info, could make a lot easier run examples, and enter easily on rust and complex crates.
### Notes
The basic working idea could be just enough, check which libs uses a example, and only show the dependencies, we can even include all the features that are in ```Cargo.toml``` that deps.
Some edges, while the basic idea can be more easily implemented, there is some points that can cause noise, actually include all features in examples is not right, the reason is simple, if is there a requested feature this imply "you need this features to make it run", which will not be always true, because all the tests and docs uses the same deps with the same features, the question here is:
¿Is possible to auto-detect which features are the needed ones for an example to just include that ones?
If is not possible, this would cause a breaking change, because implement this extra step also imply to choose example by example which features in which crates are needed, but don't worry, I think just include all of them rn would be great, this point here could be checked later, not rn, still would be nice to have.
If is possible to auto-detect, would allow us to have even better examples!
Thx!