From c9d2c954b5502f5bed8a40b9aa636df7926b0758 Mon Sep 17 00:00:00 2001 From: Jens Schuppe Date: Fri, 18 Jan 2019 10:12:33 +0100 Subject: [PATCH] Provide MKDocs documentation --- README.md | 32 +++++++++++++------ README_DE.md | 68 --------------------------------------- docs/german.md | 87 ++++++++++++++++++++++++++++++++++++++++++++++++++ docs/index.md | 1 + mkdocs.yml | 20 ++++++++++++ 5 files changed, 131 insertions(+), 77 deletions(-) delete mode 100644 README_DE.md create mode 100644 docs/german.md create mode 120000 docs/index.md create mode 100644 mkdocs.yml diff --git a/README.md b/README.md index 152c651..610f50a 100644 --- a/README.md +++ b/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) diff --git a/README_DE.md b/README_DE.md deleted file mode 100644 index 72b0381..0000000 --- a/README_DE.md +++ /dev/null @@ -1,68 +0,0 @@ -#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 unsauberen 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". 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, das 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-Project: http://www.openstreetmap.org -* Open-Street-Map-Server: http://nominatim.openstreetmap.org/ -* Beschreibung der API: http://wiki.openstreetmap.org/wiki/API_v0.6 diff --git a/docs/german.md b/docs/german.md new file mode 100644 index 0000000..0cce261 --- /dev/null +++ b/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) diff --git a/docs/index.md b/docs/index.md new file mode 120000 index 0000000..32d46ee --- /dev/null +++ b/docs/index.md @@ -0,0 +1 @@ +../README.md \ No newline at end of file diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 0000000..8bb857b --- /dev/null +++ b/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