Provide MKDocs documentation

README.md

@@ -1,16 +1,30 @@
-#SYSTOPIA OpenStreetMap CiviCRM GeoCoder
+# OpenStreetMap CiviCRM GeoCoder
 
-This CiviCRM extension adds the Nominatim OpenStreetMap server as a geocoding option. Just install the extension, and activate via "Administer" => "System Settings" => "Mapping and Geocoding".
+This CiviCRM extension adds the Nominatim OpenStreetMap server as a geocoding
+option. Just install the extension, and activate via *Administer*
+→ *System Settings* → *Mapping and Geocoding*.
 
-Disclaimer: This CiviCRM extension requests geodata from nominatim.osm.org, a service of OpenStreetMap Foundation. We have been advised that OSM servers might not be suitable for massive data requests, but so far could not get precise information on what this exactly means. Also, we don't know what the consequences of requests too massive for the OSM infrastructure might be. Therefore we recommend that you consider using the throttling option for the "Geocode and Parse Adresses" cronjob if processing data sets containing more than 10.000 addresses.
+Disclaimer: This CiviCRM extension requests geodata from nominatim.osm.org, a
+service of OpenStreetMap Foundation. We have been advised that OSM servers might
+not be suitable for massive data requests, but so far could not get precise
+information on what this exactly means. Also, we don't know what the
+consequences of requests too massive for the OSM infrastructure might be.
+Therefore we recommend that you consider using the throttling option for the
+"Geocode and Parse Adresses" cronjob if processing data sets containing more
+than 10.000 addresses.
 
-Find the [German README here](https://github.com/systopia/de.systopia.osm/blob/master/README_DE.md).
+Find the [German README here](german.md).
 
-Remark: Be careful when activating the "Geocode and Parse Addresses" scheduled job. It will try to look up all addresses that have not been geocoded yet. That, however, includes all the addresses that couldn't be successfully completed the last time - causing the same failed addresses to be queried again and again.
+Remark: Be careful when activating the "Geocode and Parse Addresses" scheduled
+job. It will try to look up all addresses that have not been geocoded yet. That,
+however, includes all the addresses that couldn't be successfully completed the
+last time - causing the same failed addresses to be queried again and again.
 
-For most scenarios it should be sufficient to run the job once, since newly entered addresses and address changes should be automatically geocoded.
+For most scenarios it should be sufficient to run the job once, since newly
+entered addresses and address changes should be automatically geocoded.
 
 Links:
-*   Open-Street-Map-Project:    http://www.openstreetmap.org
-*   Open-Street-Map-Server:     http://nominatim.openstreetmap.org/
-*   API specs:                  http://wiki.openstreetmap.org/wiki/API_v0.6
+
+* [Open-Street-Map-Project](http://www.openstreetmap.org)
+* [Open-Street-Map-Server](http://nominatim.openstreetmap.org)
+* [API specs](http://wiki.openstreetmap.org/wiki/API_v0.6)

docs/german.md

@@ -0,0 +1,87 @@
+# Kurze Beschreibung der SYSTOPIA OSM-Extension
+
+Die OSM-Extension erweitert die in CiviCRM nativen Geocoding-Optionen.
+Nativ können Koordinaten für Adressen von Yahoo oder Google abgerufen werden.
+Mit der OSM-Extension können Koordinaten auch von Open-Street-Map bezogen
+werden.
+
+## Allgemeine Funktionsweise
+
+Die Funktionsweise entspricht den nativen Geo-Coding-Optionen:
+*   Beim Anlegen oder Aktualisieren von Adressen wird ein Hook aufgerufen, der
+    die zugehörigen Koordinaten entsprechend der Geocoding-Konfiguration von
+    einem Server herunter lädt.
+*   Außerdem steht ein "Scheduled Job" zur Verfügung, der das Ermitteln aller
+    noch fehlenden Daten anstößt.
+
+## Allgemeine Anwendung
+
+1.  OSM-Extension installieren und aktivieren.
+2.  Unter "Administer"->"System Settings"->"Mapping and Geocoding"
+    für "Geocoding Provider" "OpenStreetMapCoding" auswählen.
+    1.  Beim Anlegen oder Verändern von Adress-Daten werden die Koordinaten
+        ermittelt und gespeichert.
+    2.  Unter "Administer"->"System Settings"->"Scheduled Jobs"
+        "Geocode and Parse Addresses" konfigurieren und aktivieren.
+        Dieser Job ermittelt für alle Adressen die Koordinaten, sofern sie noch
+        nicht existieren.
+4.  Möchte man generell vermeiden, dass bereits gesetzte Koordinaten vom
+    Geocoding überschrieben werden, so kann für die Koordinaten die Option
+    "Override automatic geocoding" aktiviert werden.
+
+## Umgang mit der API
+
+Fehlerhafte Adress-Daten werden nicht bereinigt. Der Api-Call wird mit den Daten
+generiert, die in der Datenbank vorgefunden werden.
+
+Fünf Fälle werden unterschieden:
+
+1.  Adresse ist unvollständig:
+    Es fehlen Angaben für das Land, die Stadt oder die Straße.
+    Um die Stadt zu identifizieren reicht in der Regel entweder der Name oder
+    die Postleitzahl.
+2.  Die Antwort der API kann nicht verarbeitet werden.
+3.  Die Adresse kann vom Server nicht identifiziert werden.
+4.  Die Adresse kann vom Server nicht eindeuting aufgelöst werden.
+    Es werden Daten für mehrere Orte zurückgegeben.
+5.  Die Adresse kann eindeutig aufgelöst werden.
+
+Die OSM-Extension verhält sich wie folgt:
+
+1.  Die Koordinaten in CiviCRM werden auf NULL gesetzt.
+2.  Die Koordinaten in CiviCRM bleiben unangetastet.
+3.  Die Koordinaten in CiviCRM werden auf NULL gesetzt.
+4.  Es werden die Koordinaten des ersten zurückgegebenen Ortes verwendet.
+5.  Die Koordinaten des zurückgegebenen Ortes werden gespeichert.
+
+## Bekannte Probleme und Fehler
+
+*   Bei unsauberem Datenstand können viele Adressen nicht aufgelöst werden.
+
+Darüber hinaus sind keine Fehler bekannt.
+
+Vorsicht ist bei der Aktivierung des geplanten Jobs
+"Geocode and Parse Addresses" geboten. Dort werden alle noch nicht aufgelösten
+Adressen zum geokodieren geschickt. Das beinhaltet aber leider auch diejenigen
+Adressen, die beim letzten Mal fehlgeschlagen sind - was dazu führt, dass diese
+fehlerhaften Adressen immer und immer wieder angefragt werden.
+
+In der Regel ist dieser aber gar nicht notwendig; Neu eingetragene Adressen und
+Adressänderungen werden automatisch neu aufgelöst. Daher reicht es meist, den
+Job "Geocode and Parse Addresses" nach Installation einmal manuell auszuführen
+und nicht als geplanten Job zu aktivieren.
+
+Bei großen Datensets kann das manuelle Auslösen einen Tiemout verursachen - in
+diesen Fällen empfehlen wir, den Cronjob zu aktivieren und nach einem
+erfolgreichen Abschluss wieder zu deaktivieren.
+
+## Verbesserungsmöglichkeiten
+
+*   Aufbereitung der Adress-Daten vor jedem API-Call um eine höhere Erfolgs-
+    Quote zu erlangen.
+*   Adress-Daten anhand der Rückgabe-Werte des Servers vervollständigen.
+
+## Links:
+* [Open-Street-Map-Projekt](http://www.openstreetmap.org)
+* [Open-Street-Map-Server](http://nominatim.openstreetmap.org)
+* [API-Beschreibung](http://wiki.openstreetmap.org/wiki/API_v0.6)

docs/index.md

@@ -0,0 +1 @@
+../README.md

mkdocs.yml

@@ -0,0 +1,20 @@
+site_name: OpenStreetMap CiviCRM GeoCoder
+repo_url: https://github.com/systopia/de.systopia.osm
+theme: material
+
+pages:
+- Home: index.md
+- 'German README': german.md
+
+markdown_extensions:
+- attr_list
+- admonition
+- def_list
+- codehilite
+- toc:
+    permalink: true
+- pymdownx.superfences
+- pymdownx.inlinehilite
+- pymdownx.tilde
+- pymdownx.betterem
+- pymdownx.mark