Example links in documentation of latest release point to current master implementation

[Glitchy-Tozier]

This example on the master branch seems a little outdated. Only by reading through other issues in this repo I was able to find this new example.

I'd like to suggest that at least the new example should get referenced in the newest documentation. https://docs.rs/argmin/0.4.7/argmin/solver/simulatedannealing/struct.SimulatedAnnealing.html Currently, it links to the old, outdated one.

[stefan-k]

Actually the example on the master branch is the newer one, but if you're using 0.4.7 then you will need the "older one".

Thanks for reporting this though, because the documentation on docs.rs is wrongly linking to the example on the master branch, which is not helpful at all. I will fix this hopefully soon.
Apologies for the inconveniences this as caused!

[Glitchy-Tozier]

but if you're using 0.4.7 then you will need the "older one".

I'm not sure, what you mean. Isn't 0.4.7 the newest version? Or is the one on the master branch already the example for 0.4.8 or 0.5.0?

Anyway, thank you for working on fixing the issue! :)

[stefan-k]

The master branch is currently ahead of 0.4.7 (which is the newest released version). In the master branch you will also find changes which aren't released yet. In this case for instance #139, which allows one to choose the random number generator used in SA.

[stefan-k]

I tried to fix this, but none of the options I could come up with was satisfactory:

1. Link to the latest release in Github. While it is possible to link to the tarball of the latest release, it is not possible to directly link to the code of the latest release.
2. Alternatively one could link to the tag of the latest release, which is possible; however, this would require manually changing the links in the documentation prior to every release. Both 1. and 2. would fix the problem for the documentation on docs.rs, but would break for the one on argmin-rs.github.io.
3. Add examples to the documentation. It is possible to document examples (via doc = true in Cargo.toml); however, this doesn't work for examples which require dev-dependencies, because those are not compiled for some reason. Same applies for passing --examples to cargo doc. Even if it would work, the examples would be listed on the left bar, right underneath the library name, potentially leading to confusion. Some issues/PRs that might be of relevance:

• Add links to examples folder rust-lang/docs.rs#132
• Document a binary? rust-lang/docs.rs#238
• Scrape code examples from examples/ directory for Rustdoc rust-lang/rfcs#3123
• Optionally document dev-dependencies rust-lang/cargo#3475

I would prefer it if it was possible to add the examples to the documentation directly. Since this is not possible right now I'm not sure how to properly address this right now. I might just remove the individual links in the documentation and have two dedicated links to the examples on the main page of the documentation.

[Glitchy-Tozier]

It's unfortunate that there's no optimal solution atm. Thank you for doing your best though!