docs: Add migration guide

[abmusse]

Resolves#143

[kadler]

Good first pass. Lots of good info here. In addition to the specific comments, all the "removed at a later time" should be "removed in the next major version".

[abmusse]

@kadler

I have added some updates, please re-review.

[kadler]

Let's land this after #173 is done.

[kadler]

Now that we have sphinx set up, @abmusse can you focus on getting this setup within sphinx. I think we should have a migration guide section in the nav bar and hook it in there. Also would be good to link to it from the main intro, adding some text there.

[abmusse]

@kadler

I had issues getting the emoji :rotating_light: to render properly in read the docs

I ended up copying UTF-8 Unicode Character 🚨 and pasting it into the migration guide.

Better but does not have the styling.

[kadler]

If we convert it to rst, we can use admonitions. Not sure if they are supported by mkdocs.

[kadler]

Here's what various ones look like in readthedocs:

[abmusse]

Yeah converting the migration guide to rst makes sense given that the rest of the doc files are in rst already.

[abmusse]

@kadler I've converted the migration guide from markdown to rst

[abmusse]

@kadler This is ready for re-review

[kadler]

This section is way more important to highlight than the prior one. You should be able to figure out how to connect using Connection from the docs, however you may not realize that iConn -> Connection implies a change in behavior of the callbacks. I think we definitely need some WARNING messages above to point the user at this section and mention returnError.

Something like:

"Beware that the Connection and iConn classes differ in how they call the callbacks passed to their run methods. You cannot simply replace iConn with Connection without adjusting your callbacks. See here for more info on how to do that.