Improve all warning messages

[jni]

Our warnings are pretty noisy and usually sends users on a wild Google search to find how to fix their problem. Instead we should provide informative messages everywhere that include links to relevant documentation. @stefanv suggests React.js as a good model for this.

[stefanv]

The idea here was that we would link, e.g., deprecation messages to a page that explains the issue in more detail. I think it's a good idea, but it requires infrastructure that we haven't built yet.

If I had to guess how we'd build this: add a directory of pages to the docs, pages are numbered, and links given in docs become something like https://skimage.org/ref/192-breaking-api.html and then have Netlify redirect /ref/* to https://scikit-image.org/docs/dev/*.

(If we're not hosting on Netlify yet, that's probably a good next step.)

[lagru]

As a user I like the idea, as a maintainer, I don't. We are already struggling to keep our TODO.txt and narrative documentation up to date. Even worse than verbose warning messages are messages that point to outdated or non-existent resources. If there were a way to test this or make this more reliable somehow, I wouldn't mind this. For now I'm -0.5 because I think the added maintenance burden is not worth it. Always open to arguments of course. 😉

[lagru]

Also, I'm curious what kind of warnings you'd consider noisy as I haven't really felt that pain yet.

[stefanv]

A good start would be to simply write longer messages that provide better transition instructions to the user.

Think about this for the skimage v2 transition, though: do you prefer to maintain very long messages and re-use those in different places, or could it be easier to keep webpages, with proper markdown etc., updated and link to them? Genuine question! We shouldn't build mechanisms we don't use.

We'd keep it lightweight, though; e.g. a directory of markdown files that get published automatically.