add support for ICS service docu

- define yaml format for ICS service description - add support for yaml for update_docu_links.py
5ila5 · Apr 5, 2023 · 4921f0d · 4921f0d
1 parent bc242bd
commit 4921f0d
Show file tree

Hide file tree

Showing 5 changed files with 138 additions and 31 deletions.
diff --git a/README.md b/README.md
@@ -262,6 +262,7 @@ Waste collection schedules in the following formats and countries are supported.
 - [WZV Kreis Segeberg](/doc/source/c_trace_de.md) / wzv.de
 - [ZAW Darmstadt-Dieburg](/doc/source/zaw_online_de.md) / zaw-online.de
 - [Zweckverband Abfallwirtschaft Kreis Bergstraße](/doc/source/zakb_de.md) / zakb.de
+- [Zweckverband Abfallwirtschaft Region Trier (A.R.T.)](/doc/source/ics/art_trier_de.md) / art-trier.de
 - [Zweckverband Abfallwirtschaft Saale-Orla](/doc/source/awido_de.md) / zaso-online.de
 - [Zweckverband Abfallwirtschaft Schwalm-Eder-Kreis](/doc/source/zva_sek_de.md) / zva-sek.de
 - [Zweckverband München-Südost](/doc/source/awido_de.md) / zvmso.de

diff --git a/doc/ics/art_trier_de.md b/doc/ics/art_trier_de.md
@@ -0,0 +1,24 @@
+# Zweckverband Abfallwirtschaft Region Trier (A.R.T.)
+
+Zweckverband Abfallwirtschaft Region Trier (A.R.T.) is supported by the generic [ICS](/doc/source/ics.md) source. For all available configuration options, please refer to the source description.
+
+
+## How to get the configuration arguments
+
+- Goto <https://www.art-trier.de/> and select your municipality.  
+- Scroll down to `JAHRESKALENDER FÜR IHR OUTLOOK, ETC.`  
+- Set `Wann möchten Sie erinnert werden?` to `Am Abfuhrtag`.
+- Click on `> Kalender (ICS) importieren` to get a webcal link.
+- Copy this link into the configuration (see example).
+
+## Examples
+
+### Basberg
+
+```yaml
+waste_collection_schedule:
+  sources:
+    - name: ics
+      args:
+        url: webcal://abfallkalender.art-trier.de/ics-feed/54578_basberg_1-1800.ics
+```
diff --git a/doc/ics/yaml/art_trier_de.yaml b/doc/ics/yaml/art_trier_de.yaml
@@ -0,0 +1,10 @@
+title: Zweckverband Abfallwirtschaft Region Trier (A.R.T.)
+url: https://www.art-trier.de/
+howto: |
+   - Goto <https://www.art-trier.de/> and select your municipality.  
+   - Scroll down to `JAHRESKALENDER FÜR IHR OUTLOOK, ETC.`  
+   - Set `Wann möchten Sie erinnert werden?` to `Am Abfuhrtag`.
+   - Click on `> Kalender (ICS) importieren` to get a webcal link.
+   - Copy this link into the configuration (see example).
+test_cases:
+   Basberg: { url: "webcal://abfallkalender.art-trier.de/ics-feed/54578_basberg_1-1800.ics" }
diff --git a/info.md b/info.md
@@ -20,7 +20,7 @@ Waste collection schedules from service provider web sites are updated daily, de
 | Austria | Burgenländischer Müllverband, infeo, Stadtservice Korneuburg, Umweltprofis, WSZ Moosburg |
 | Belgium | Hygea, Recycle! |
 | Canada | City of Toronto |
-| Germany | Abfall Stuttgart, Abfall-Wirtschafts-Verband Nordschwaben, Abfall.IO / AbfallPlus, Abfallbewirtschaftung Ostalbkreis, Abfallkalender Offenbach am Main, Abfallkalender Würzburg, AbfallNavi (RegioIT.de), Abfalltermine Forchheim, Abfallwirtschaft Alb-Donau-Kreis, Abfallwirtschaft Germersheim, Abfallwirtschaft Isar-Inn, Abfallwirtschaft Lahn-Dill-Kreises, Abfallwirtschaft Landkreis Böblingen, Abfallwirtschaft Landkreis Freudenstadt, Abfallwirtschaft Landkreis Harburg, Abfallwirtschaft Landkreis Kitzingen, Abfallwirtschaft Landkreis Landsberg am Lech, Abfallwirtschaft Landkreis Wolfenbüttel, Abfallwirtschaft Neckar-Odenwald-Kreis, Abfallwirtschaft Nürnberger Land, Abfallwirtschaft Ortenaukreis, Abfallwirtschaft Pforzheim, Abfallwirtschaft Rems-Murr, Abfallwirtschaft Rendsburg, Abfallwirtschaft Rheingau-Taunus-Kreis, Abfallwirtschaft Stadt Fürth, Abfallwirtschaft Stadt Nürnberg, Abfallwirtschaft Stadt Schweinfurt, Abfallwirtschaft Südholstein, Abfallwirtschaft Werra-Meißner-Kreis, Abfallwirtschaft Zollernalbkreis, Abfallwirtschafts-Zweckverband des Landkreises Hersfeld-Rotenburg, Abfallwirtschaftsbetrieb Bergisch Gladbach, Abfallwirtschaftsbetrieb Esslingen, Abfallwirtschaftsbetrieb Landkreis Ahrweiler, Abfallwirtschaftsbetrieb Landkreis Altenkirchen, Abfallwirtschaftsbetrieb Landkreis Augsburg, Abfallwirtschaftsbetrieb Landkreis Aurich, Abfallwirtschaftsverband Kreis Groß-Gerau, ALBA Berlin, ART Trier, ASO Abfall-Service Osterholz, ASR Stadt Chemnitz, AWA Entsorgungs GmbH, AWB Abfallwirtschaft Vechta, AWB Bad Kreuznach, AWB Köln, AWB Landkreis Bad Dürkheim, AWB Landkreis Fürstenfeldbruck, AWB Landkreis Göppingen, AWB Oldenburg, AWB Westerwaldkreis, AWG Kreis Warendorf, AWIDO Online, Bau & Service Oberursel, Bergischer Abfallwirtschaftverbund, Berlin Recycling, Berliner Stadtreinigungsbetriebe, Bielefeld, Bogenschütz Entsorgung, Bremer Stadtreinigung, Bürgerportal, C-Trace, CM City Media - Müllkalender, Dillingen Saar, Dinslaken, EAD Darmstadt, EGN Abfallkalender, EGST Steinfurt, EGW Westmünsterland, Entsorgungs- und Wirtschaftsbetrieb Landau in der Pfalz, Entsorgungsbetriebe Essen, Gemeinde Aschheim, Gemeinde Blankenheim, Gemeinde Bühlerzell, Gemeinde Deggenhausertal, Gemeinde Kalletal, Gemeinde Kappelrodeck, Gemeinde Kressbronn am Bodensee, Gemeinde Lindlar, Gemeinde Mittelbiberach, Gemeinde Oberstadion, Gemeinde Roetgen, Gemeinde Schutterwald, Gemeinde Senden (Westfalen), Gemeinde Unterhaching, Göttinger Entsorgungsbetriebe, Gütersloh, Halver, Heilbronn Entsorgungsbetriebe, Hohenlohekreis, Jumomind, KAEV Niederlausitz, Kommunalservice Landkreis Börde AöR, Kreis Coesfeld, Kreis Heinsberg, Kreis Pinneberg, Kreisstadt Dietzenbach, Kreisstadt St. Wendel, Kreiswirtschaftsbetriebe Goslar, KV Cochem-Zell, KWU Entsorgung Landkreis Oder-Spree, Landkreis Ansbach, Landkreis Aschaffenburg, Landkreis Bayreuth, Landkreis Berchtesgadener Land, Landkreis Calw, Landkreis Coburg, Landkreis Erding, Landkreis Erlangen-Höchstadt, Landkreis Fulda, Landkreis Gotha, Landkreis Günzburg, Landkreis Heilbronn, Landkreis Kelheim, Landkreis Kronach, Landkreis Limburg-Weilburg, Landkreis Nordwestmecklenburg, Landkreis Ostallgäu, Landkreis Rhön Grabfeld, Landkreis Rosenheim, Landkreis Rotenburg (Wümme), Landkreis Roth, Landkreis Schweinfurt, Landkreis Schwäbisch Hall, Landkreis Schwäbisch Hall, Landkreis Sigmaringen, Landkreis Südliche Weinstraße, Landkreis Tirschenreuth, Landkreis Tübingen, Landkreis Weißenburg-Gunzenhausen, Landkreis Wittmund, Landkreisbetriebe Neuburg-Schrobenhausen, Landratsamt Aichach-Friedberg, Landratsamt Dachau, Landratsamt Main-Tauber-Kreis, Landratsamt Traunstein, Landratsamt Unterallgäu, Ludwigshafen am Rhein, MZV Biedenkopf, MüllALARM / Schönmackers, Müllmax, Neunkirchen Siegerland, Neustadt a.d. Waldnaab, Pullach im Isartal, RegioEntsorgung Städteregion Aachen, Rhein-Hunsrück Entsorgung (RHE), Rhein-Neckar-Kreis, Sector 27 - Datteln, Marl, Oer-Erkenschwick, Stadt Aachen, Stadt Arnsberg, Stadt Bayreuth, Stadt Cottbus, Stadt Dorsten, Stadt Ehingen, Stadt Emden, Stadt Emmendingen, Stadt Fulda, Stadt Kaufbeuren, Stadt Kraichtal, Stadt Landshut, Stadt Memmingen, Stadt Messstetten, Stadt Norderstedt, Stadt Overath, Stadt Regensburg, Stadt Solingen, Stadt Unterschleißheim, Stadt Willich, Stadtreinigung Dresden, Stadtreinigung Hamburg, Stadtreinigung Leipzig, StadtService Brühl, STL Lüdenscheid, Städteservice Raunheim Rüsselsheim, Südbrandenburgischer Abfallzweckverband, VIVO Landkreis Miesbach, WBO Wirtschaftsbetriebe Oberhausen, Wermelskirchen, WGV Recycling GmbH, Wolfsburger Abfallwirtschaft und Straßenreinigung, WZV Kreis Segeberg, ZAW Darmstadt-Dieburg, Zweckverband Abfallwirtschaft Kreis Bergstraße, Zweckverband Abfallwirtschaft Saale-Orla, Zweckverband Abfallwirtschaft Schwalm-Eder-Kreis, Zweckverband München-Südost |
+| Germany | Abfall Stuttgart, Abfall-Wirtschafts-Verband Nordschwaben, Abfall.IO / AbfallPlus, Abfallbewirtschaftung Ostalbkreis, Abfallkalender Offenbach am Main, Abfallkalender Würzburg, AbfallNavi (RegioIT.de), Abfalltermine Forchheim, Abfallwirtschaft Alb-Donau-Kreis, Abfallwirtschaft Germersheim, Abfallwirtschaft Isar-Inn, Abfallwirtschaft Lahn-Dill-Kreises, Abfallwirtschaft Landkreis Böblingen, Abfallwirtschaft Landkreis Freudenstadt, Abfallwirtschaft Landkreis Harburg, Abfallwirtschaft Landkreis Kitzingen, Abfallwirtschaft Landkreis Landsberg am Lech, Abfallwirtschaft Landkreis Wolfenbüttel, Abfallwirtschaft Neckar-Odenwald-Kreis, Abfallwirtschaft Nürnberger Land, Abfallwirtschaft Ortenaukreis, Abfallwirtschaft Pforzheim, Abfallwirtschaft Rems-Murr, Abfallwirtschaft Rendsburg, Abfallwirtschaft Rheingau-Taunus-Kreis, Abfallwirtschaft Stadt Fürth, Abfallwirtschaft Stadt Nürnberg, Abfallwirtschaft Stadt Schweinfurt, Abfallwirtschaft Südholstein, Abfallwirtschaft Werra-Meißner-Kreis, Abfallwirtschaft Zollernalbkreis, Abfallwirtschafts-Zweckverband des Landkreises Hersfeld-Rotenburg, Abfallwirtschaftsbetrieb Bergisch Gladbach, Abfallwirtschaftsbetrieb Esslingen, Abfallwirtschaftsbetrieb Landkreis Ahrweiler, Abfallwirtschaftsbetrieb Landkreis Altenkirchen, Abfallwirtschaftsbetrieb Landkreis Augsburg, Abfallwirtschaftsbetrieb Landkreis Aurich, Abfallwirtschaftsverband Kreis Groß-Gerau, ALBA Berlin, ART Trier, ASO Abfall-Service Osterholz, ASR Stadt Chemnitz, AWA Entsorgungs GmbH, AWB Abfallwirtschaft Vechta, AWB Bad Kreuznach, AWB Köln, AWB Landkreis Bad Dürkheim, AWB Landkreis Fürstenfeldbruck, AWB Landkreis Göppingen, AWB Oldenburg, AWB Westerwaldkreis, AWG Kreis Warendorf, AWIDO Online, Bau & Service Oberursel, Bergischer Abfallwirtschaftverbund, Berlin Recycling, Berliner Stadtreinigungsbetriebe, Bielefeld, Bogenschütz Entsorgung, Bremer Stadtreinigung, Bürgerportal, C-Trace, CM City Media - Müllkalender, Dillingen Saar, Dinslaken, EAD Darmstadt, EGN Abfallkalender, EGST Steinfurt, EGW Westmünsterland, Entsorgungs- und Wirtschaftsbetrieb Landau in der Pfalz, Entsorgungsbetriebe Essen, Gemeinde Aschheim, Gemeinde Blankenheim, Gemeinde Bühlerzell, Gemeinde Deggenhausertal, Gemeinde Kalletal, Gemeinde Kappelrodeck, Gemeinde Kressbronn am Bodensee, Gemeinde Lindlar, Gemeinde Mittelbiberach, Gemeinde Oberstadion, Gemeinde Roetgen, Gemeinde Schutterwald, Gemeinde Senden (Westfalen), Gemeinde Unterhaching, Göttinger Entsorgungsbetriebe, Gütersloh, Halver, Heilbronn Entsorgungsbetriebe, Hohenlohekreis, Jumomind, KAEV Niederlausitz, Kommunalservice Landkreis Börde AöR, Kreis Coesfeld, Kreis Heinsberg, Kreis Pinneberg, Kreisstadt Dietzenbach, Kreisstadt St. Wendel, Kreiswirtschaftsbetriebe Goslar, KV Cochem-Zell, KWU Entsorgung Landkreis Oder-Spree, Landkreis Ansbach, Landkreis Aschaffenburg, Landkreis Bayreuth, Landkreis Berchtesgadener Land, Landkreis Calw, Landkreis Coburg, Landkreis Erding, Landkreis Erlangen-Höchstadt, Landkreis Fulda, Landkreis Gotha, Landkreis Günzburg, Landkreis Heilbronn, Landkreis Kelheim, Landkreis Kronach, Landkreis Limburg-Weilburg, Landkreis Nordwestmecklenburg, Landkreis Ostallgäu, Landkreis Rhön Grabfeld, Landkreis Rosenheim, Landkreis Rotenburg (Wümme), Landkreis Roth, Landkreis Schweinfurt, Landkreis Schwäbisch Hall, Landkreis Schwäbisch Hall, Landkreis Sigmaringen, Landkreis Südliche Weinstraße, Landkreis Tirschenreuth, Landkreis Tübingen, Landkreis Weißenburg-Gunzenhausen, Landkreis Wittmund, Landkreisbetriebe Neuburg-Schrobenhausen, Landratsamt Aichach-Friedberg, Landratsamt Dachau, Landratsamt Main-Tauber-Kreis, Landratsamt Traunstein, Landratsamt Unterallgäu, Ludwigshafen am Rhein, MZV Biedenkopf, MüllALARM / Schönmackers, Müllmax, Neunkirchen Siegerland, Neustadt a.d. Waldnaab, Pullach im Isartal, RegioEntsorgung Städteregion Aachen, Rhein-Hunsrück Entsorgung (RHE), Rhein-Neckar-Kreis, Sector 27 - Datteln, Marl, Oer-Erkenschwick, Stadt Aachen, Stadt Arnsberg, Stadt Bayreuth, Stadt Cottbus, Stadt Dorsten, Stadt Ehingen, Stadt Emden, Stadt Emmendingen, Stadt Fulda, Stadt Kaufbeuren, Stadt Kraichtal, Stadt Landshut, Stadt Memmingen, Stadt Messstetten, Stadt Norderstedt, Stadt Overath, Stadt Regensburg, Stadt Solingen, Stadt Unterschleißheim, Stadt Willich, Stadtreinigung Dresden, Stadtreinigung Hamburg, Stadtreinigung Leipzig, StadtService Brühl, STL Lüdenscheid, Städteservice Raunheim Rüsselsheim, Südbrandenburgischer Abfallzweckverband, VIVO Landkreis Miesbach, WBO Wirtschaftsbetriebe Oberhausen, Wermelskirchen, WGV Recycling GmbH, Wolfsburger Abfallwirtschaft und Straßenreinigung, WZV Kreis Segeberg, ZAW Darmstadt-Dieburg, Zweckverband Abfallwirtschaft Kreis Bergstraße, Zweckverband Abfallwirtschaft Region Trier (A.R.T.), Zweckverband Abfallwirtschaft Saale-Orla, Zweckverband Abfallwirtschaft Schwalm-Eder-Kreis, Zweckverband München-Südost |
 | Lithuania | Kauno švara |
 | Luxembourg | Esch-sur-Alzette |
 | Netherlands | ACV Group, Alpen an den Rijn, Area Afval, Avalex, Avri, Bar Afvalbeheer, Circulus, Cyclus NV, Dar, Den Haag, GAD, Gemeente Almere, Gemeente Berkelland, Gemeente Cranendonck, Gemeente Hellendoorn, Gemeente Lingewaard, Gemeente Meppel, Gemeente Middelburg + Vlissingen, Gemeente Peel en Maas, Gemeente Schouwen-Duiveland, Gemeente Sudwest-Fryslan, Gemeente Venray, Gemeente Voorschoten, Gemeente Waalre, Gemeente Westland, HVC Groep, Meerlanden, Mijn Blink, PreZero, Purmerend, RAD BV, Reinis, Spaarnelanden, Twente Milieu, Waardlanden, Ximmio, ZRD |

diff --git a/update_docu_links.py b/update_docu_links.py
@@ -11,7 +11,7 @@
 SECRET_FILENAME = "secrets.yaml"
 SECRET_REGEX = re.compile(r"!secret\s(\w+)")
 
-BLACK_LIST = {"ics", "static", "example"}
+BLACK_LIST = {"/doc/source/ics.md", "/doc/source/static.md", "/doc/source/example.md"}
 
 START_COUNTRY_SECTION = "<!--Begin of country section-->"
 END_COUNTRY_SECTION = "<!--End of country section-->"
@@ -34,16 +34,47 @@ def end(self):
 
 
 def main():
-    parser = argparse.ArgumentParser(description="Test sources.")
+    parser = argparse.ArgumentParser(description="Update docu links.")
     # args = parser.parse_args()
 
+    sources = []
+
+    browse_sources(sources)
+    browse_ics_yaml(sources)
+
+    # sort into countries
+    country_code_map = make_country_code_map()
+    countries = {}
+
+    orphans = []
+    for s in sources:
+        if s.filename in BLACK_LIST:
+            continue  # skip
+
+        # extract country code
+        code = s.country
+        if code in country_code_map:
+            countries.setdefault(country_code_map[code]["name"], []).append(s)
+        else:
+            orphans.append(s)
+
+    if len(orphans) > 0:
+        print("Orphaned sources without country =========================")
+        for o in orphans:
+            print(o)
+
+    update_readme_md(countries)
+    update_info_md(countries)
+
+
+def browse_sources(sources):
+    """Browse all .py files in the `source` directory"""
     package_dir = (
         Path(__file__).resolve().parents[0]
         / "custom_components"
         / "waste_collection_schedule"
     )
     source_dir = package_dir / "waste_collection_schedule" / "source"
-    print(source_dir)
 
     # add module directory to path
     site.addsitedir(str(package_dir))
@@ -54,7 +85,6 @@ def main():
     )
 
     modules = {}
-    sources = []
 
     # retrieve all data from sources
     for f in files:
@@ -66,9 +96,10 @@ def main():
         url = module.URL
         country = getattr(module, "COUNTRY", f.split("_")[-1])
 
+        filename = f"/doc/source/{f}.md"
         if title is not None:
             sources.append(
-                SourceInfo(filename=f, title=title, url=url, country=country)
+                SourceInfo(filename=filename, title=title, url=url, country=country)
             )
 
         extra_info = getattr(module, "EXTRA_INFO", [])
@@ -77,37 +108,80 @@ def main():
         for e in extra_info:
             sources.append(
                 SourceInfo(
-                    filename=f,
+                    filename=filename,
                     title=e.get("title", title),
                     url=e.get("url", url),
                     country=e.get("country", country),
                 )
             )
 
-    # sort into countries
-    country_code_map = make_country_code_map()
-    countries = {}
-    orphans = []
-    for s in sources:
-        if s.filename in BLACK_LIST:
-            continue  # skip
-
-        # extract country code
-        code = s.country
-        if code in country_code_map:
-            countries.setdefault(country_code_map[code]["name"], []).append(s)
-        else:
-            orphans.append(s)
-
-    update_readme_md(countries)
-    update_info_md(countries)
     update_awido_de(modules)
     update_ctrace_de(modules)
 
-    if len(orphans) > 0:
-        print("Orphaned =========================")
-        for o in orphans:
-            print(o)
+
+def browse_ics_yaml(sources):
+    """Browse all .yaml files which are descriptions for the ICS source"""
+    doc_dir = Path(__file__).resolve().parents[0] / "doc"
+    yaml_dir = doc_dir / "ics" / "yaml"
+    md_dir = doc_dir / "ics"
+
+    files = filter(
+        lambda x: x != "__init__",
+        map(lambda x: x.stem, yaml_dir.glob("*.yaml")),
+    )
+    files = yaml_dir.glob("*.yaml")
+    for f in files:
+        with open(f) as stream:
+            # write markdown file
+            filename = (md_dir / f.name).with_suffix(".md")
+            data = yaml.safe_load(stream)
+            write_ics_md_file(filename, data)
+
+            # extract country code
+            sources.append(
+                SourceInfo(
+                    filename=f"/doc/source/ics/{filename.name}",
+                    title=data["title"],
+                    url=data["url"],
+                    country=data.get("country", f.stem.split("_")[-1]),
+                )
+            )
+
+
+def write_ics_md_file(filename, data):
+    """Write a markdown file for a ICS .yaml file"""
+    md = f"# {data['title']}\n"
+    md += "\n"
+    md += f"{data['title']} is supported by the generic [ICS](/doc/source/ics.md) source. For all available configuration options, please refer to the source description.\n"
+    md += "\n"
+    if "description" in data:
+        md += f"{data['description']}\n"
+    md += "\n"
+    md += "## How to get the configuration arguments\n"
+    md += "\n"
+    md += f"{data['howto']}"
+    md += "\n"
+    md += "## Examples\n"
+    md += "\n"
+    for title, tc in data["test_cases"].items():
+        md += f"### {title}\n"
+        md += "\n"
+        md += "```yaml\n"
+        md += "waste_collection_schedule:\n"
+        md += "  sources:\n"
+        md += "    - name: ics\n"
+        md += "      args:\n"
+        md += multiline_indent(yaml.dump(tc).rstrip("\n"), 8) + "\n"
+        md += "```\n"
+        # md += "\n"
+    with open(filename, "w") as f:
+        f.write(md)
+
+
+def multiline_indent(s, numspaces):
+    """Indent all lines within the given string by <numspace> spaces"""
+    lines = [(numspaces * " ") + line for line in s.split("\n")]
+    return "\n".join(lines)
 
 
 def beautify_url(url):
@@ -128,9 +202,7 @@ def update_readme_md(countries):
 
         for e in sorted(countries[country], key=lambda e: e.title.lower()):
             # print(f"  {e.title} - {beautify_url(e.url)}")
-            str += (
-                f"- [{e.title}](/doc/source/{e.filename}.md) / {beautify_url(e.url)}\n"
-            )
+            str += f"- [{e.title}]({e.filename}) / {beautify_url(e.url)}\n"
 
         str += "</details>\n"
         str += "\n"