Improve documentation and examples

[JoerivanEngelen]

If I'm not mistaken: up to now, documentation was not a priority in the development of XMI.
Right now, I'm missing a few chunks of information that are required by an external user to use XMI.

First of all, there is no document available specific to XMI. This document could describe what XMI exactly is and its' relation to BMI. Furthermore it can describe how a user can modify his own code to use XMI. We can follow the BMI example. As a repository for this XMI document is not yet available, I thought the xmipy github is the best place to raise this issue.

Secondly, the README of the xmipy repository is now very specific to Modflow6. One sentence should be added that describes what is extended from bmipy: Namely that XMI exposes the outer iteration loops, which is required in the coupling of some hydrological kernels, and that xmipy provides the python bindings for these extra functions.

Thirdly, the current examples in the xmipy repository have paths to local folders in them. These scripts are an OK start if you are familiar with Modflow6 models and their structure. However, if you are not, having a reproducible example is a bare necessity. Probably the best approach is to either copy some of the examples in the Modflow 6 example repository as self-contained models, or download them with a provided python script, and use these models as an example. An alternative is introducing a flopy dependency and generating examples with that, but that could confuse users as they then also have to learn the basics of the flopy API.

[mjr-deltares]

This is by no means a solved issue. The modflowapi project will take up a lot of MODFLOW related functionality and context but that leaves xmipy in the same place: we cannot test it unless we create a generic shared library (stub) with sufficient functionality or we go against proper dependency management and have our tests depend on e.g. flopy, like we do now...

To overcome this, as for a proper documentation, we need priority and resources. Currently these are not there, and since the issue has been open for so long, I will close it now.