Improved documentation

README.md

@@ -20,6 +20,8 @@ from vipscore_common.entities import Result, ModelConfiguration, WeatherObservat
 from vipscore_common.data_utils import *
 ```
 
+Read more about [implementing a VIPS Model using Python](/docs/VIPSModel.md)
+
 ## Developer guide
 
 ### Unit tests

docs/VIPSModel.md

+<img src="illustrations/vipslogo_512.png" alt="VIPS Logo" height="250"/>
+
+# How to implement a VIPS Model in Python
+VIPS was originally written in Java, and the models to be deployed were also required to be written in a language that could run on the Java Virtual Machine (JVM). This is in principle [a lot of languages](https://en.wikipedia.org/wiki/List_of_JVM_languages), but only a few of those are practical to integrate with the [original VIPSCore server](https://gitlab.nibio.no/VIPS/VIPSCore). Back in the early 2010s, Python was considered to work well on JVM, but this is no longer the case, as Jython is only compatible with Python <= 2.7. Python has since then become widely used for numeric analysis and model development, and the number of model implementers with Python skills vastly outnumbers Java mastering model developers. 
+
+To resolve this, we have reimplemented the [VIPSCore web services in Python](https://gitlab.nibio.no/VIPS/VIPSCore-Python), allowing models implemented in Python to be run on/from that server. The web service endpoints of VIPSCore-Python are (or should be) identical to the original VIPSCore service. 
+
+In Java, all models have to implement the [Model interface](https://gitlab.nibio.no/VIPS/VIPSCommon/-/blob/develop/src/main/java/no/nibio/vips/model/Model.java). This enables the VIPSCore server to look the Classpath for Java classes that fulfill the contract (the interface), index them and make them available through lookup endpoints, for example: https://coremanager.vips.nibio.no/models/ 
+
+Python does not have interfaces. It does however have [Abstract Base Classes](https://docs.python.org/3/library/abc.html), which do the job well enough. It's possible for a Python application to search on its Pythonpath for classes that are children of a specific class.
+
+```python
+# Simplified code excerpt from VIPSCore-Python that indexes models 
+# extending the VIPSModel Abstract Base Class (which is part of this package)
+from vipscore_common.vips_model import VIPSModel
+models = {}
+for vipsmodel_subclass in VIPSModel.__subclasses__():
+        # We must have an instance to reach the property
+        vipsmodel_instance = vipsmodel_subclass()
+        models[vipsmodel_instance.model_id] = vipsmodel_subclass
+```
+
+## The VIPSModel Abstract Base Class
+The VIPSModel Abstract Base Class is part of VIPSCore-Python-Common (this package). You can find it in `src/vipscore_common/vips_model.py`. Along with the data classes in `src/vipscore_common/entities.py` and util methods in `src/vipscore_common/data_utils.py`, you have the basic tools for implementing a VIPSModel. You have to [create your own package](https://realpython.com/pypi-publish-python-package/), and implement the model there. 
+
+The top of your implementing class could be e.g.:
+
+```python
+from vipscore_common.vips_model import VIPSModel
+from vipscore_common.entities import Result, ModelConfiguration, WeatherObservation
+from vipscore_common.data_utils import *
+
+class MyModel(VIPSModel):
+    """
+        Model short description
+    """
+```
+It is highly recommended to study the [ReferenceModel](https://gitlab.nibio.no/VIPS/models/python/referencemodel) for how to proceed on the implementation. For how to deploy the implemented model on VIPSCore-Python, please see the [VIPSCore-Python documentation](https://gitlab.nibio.no/VIPS/VIPSCore-Python#install-vips-models).
\ No newline at end of file