Improve documentation, add documentation testing, and make all examples into scripts.

[erikmannerfelt]

This was a hard one, including environment variables and all kinds of weird errors!

Fixed warnings and incorrect docstrings

There were quite many warnings before when building the documentation. I've made sure that all of them have been fixed.

Documentation build tests

I've added tests for all example scripts (I'll get more to that in a second) and for building the documentation. Now, theoretically, ReadTheDocs should always build if the build check on GitHub passes. Makes for easier maintainability in the long term, as a PR that passes the build check should be compatible with ReadTheDocs (right now, builds might pass but then the documentation fails to build!).

More future-frendly examples structure.

Finally, since we already have had trouble with outdated examples, all example code is now in docs/source/code/*.py. This has many advantages:

1. Linters and formatters can locally help with the scripts to make sure that they're correct.
2. It's easier to debug, as the code can be run without rebuilding the entire documentation.
3. Inline code in rst is awkward to write
4. It allows testing the code externally (if an example is outdated, it won't pass the build check!)

See the result

If you're interested, you can see how the documentation will look here:
https://xdem-erikm.readthedocs.io/en/improve_docs/index.html

[erikmannerfelt]

This partly tackles #53 as invalid docstrings will show up in the build check (as warnings if they are minor, and failed builds if they are major).

#75 and #92 were only needed because we didn't have a good validation technique for the documentation examples. This should solve it.

[rhugonnet]

Nothing to say except that this is going to be super useful!

I'm wondering if this kind of "good practice" won't eventually (in 5-year time?) be included in a more user-friendly way to GitHub. I hope so.
The advantage is that we really get to know how this all works (well.. mostly you Erik!)

[rhugonnet]

so literalinclude is kind of the key here :D

[rhugonnet]

time will tell !

[rhugonnet]

very nice

[erikmannerfelt]

Thank you for the feedback, @rhugonnet!

I wanted to see if other packages used similar testing, so I checked rasterio.

1. They recommend installing rio=0.24 and gdal=1.11 in their installation page
2. I haven't found any incorrect syntax, but many statements are only really pseudocode. See here; what are the kwargs!? (turns out they're width, height, cound, transform, dtype and crs...)
3. There are some typos here and there; dtype-uint8 in the output instead of dtype=uint8.

[adehecq]

Thank you for the feedback, @rhugonnet!

I wanted to see if other packages used similar testing, so I checked rasterio.

1. They recommend installing rio=0.24 and gdal=1.11 in their [installation page](https://rasterio.readthedocs.io/en/latest/installation.html#windows)

2. I haven't found any incorrect syntax, but many statements are only really pseudocode. [See here](https://rasterio.readthedocs.io/en/latest/topics/switch.html#format-drivers); what are the kwargs!? (turns out they're width, height, cound, transform, dtype and crs...)

3. There are some typos [here and there](https://rasterio.readthedocs.io/en/latest/topics/switch.html#valid-data-masks); `dtype-uint8` in the output instead of `dtype=uint8`.

Does this mean we're now doing better than rasterio?! :-)