improve documentation

- add debugging chapter
- fix lint warnings

README.md

@@ -60,6 +60,7 @@ Currently the following service providers are supported:
 - [Stonnington City Council, Melbourne](./doc/source/stonnington_vic_gov_au.md)
 
 ### Belgium
+
 - [Hygea.be](./doc/source/hygea_be.md)
 - [Recycle! / RecycleApp.be](./doc/source/recycleapp_be.md)
 
@@ -100,10 +101,12 @@ Currently the following service providers are supported:
 - [Gore, Invercargill & Southland](./doc/source/wastenet_org_nz.md)
 
 ### Sweden
+
 - [Lerum.se](./doc/source/lerum_se.md)
 - [Sysav.se](./doc/source/sysav_se.md)
 
 ### Switzerland
+
 - [Lindau.ch](./doc/source/lindau_ch.md)
 
 ### United States of America
@@ -574,7 +577,6 @@ Prerequisites: You already have dedicated sensors per waste type and want to sho
 
 Add `add_days_to: True` to the configuration of all sensors you want to sort. This will add the attribute `daysTo` which can be used by e.g. [auto-entities](https://github.com/thomasloven/lovelace-auto-entities) to sort entities by day of next collection.
 
-
 ## How to add new sources
 
 1. Create a new source in folder `custom_components/waste_collection_schedule/waste_collection_schedule/source` with the lower case url of your service provider (e.g. `abc_com.py` for `http://www.abc.com`).
@@ -589,6 +591,8 @@ Add `add_days_to: True` to the configuration of all sensors you want to sort. Th
 
 Filtering of data for waste types or time periods is a functionality of the framework and shall not be done by a source.
 
+### Source Code Example
+
 Example for `abc_com.py`:
 
 ```py
@@ -623,5 +627,52 @@ class Source:
 
 See also: [custom_components/waste_collection_schedule/waste_collection_schedule/source/example.py](./custom_components/waste_collection_schedule/waste_collection_schedule/source/example.py)
 
-##Guides
+### Debugging
-There is an HowTo Video in german: https://youtu.be/MzQgARDvRww
+
+Debugging a source within Home Assistant is not recommended because startup of HA is far too slow for fast debugging cycles.
+
+Instead, there is a test fixture which allows to run a source from the command line. The fixture is a Python script which is located here:
+
+`custom_components/waste_collection_schedule/waste_collection_schedule/test/test_sources.py`.
+
+The script uses the test cases defined in the source file and runs the source with the arguments of every test case.
+
+By default (without additional arguments), the script tests every source file in the `source` folder and prints the number of found entries for every test case.
+
+Example output for `abfall_io`:
+
+```text
+Testing source abfall_io ...
+  found 269 entries for Waldenbuch
+  found 55 entries for Landshut
+  found 101 entries for Schoenmackers
+  found 139 entries for Freudenstadt
+  found 190 entries for Ludwigshafen am Rhein
+```
+
+The script supports the following options:
+
+Option | Argument | Description
+---- | ----- | ----
+`-s` | SOURCE | [Source name](https://github.com/mampfes/hacs_waste_collection_schedule#source-configuration-variables) (source file name without ending `.py`)
+`-l` | - | List all found dates
+`-i` | - | Add icon name to output. Only effective together with `-l`.
+
+For debugging purposes of a single source, it is recommended to use the `-s SOURCE` option.
+
+Example for `abc_com.py`:
+
+```bash
+test_sources.py -s abc_com -l -i
+```
+
+## Videos
+
+There is some video's on YouTube:
+
+### German
+
+- [Bunte Mülltonnenerinnerung mit Home Assistant](https://youtu.be/MzQgARDvRww)
+- [Abfall Kalender in Home Assistant mit Erinnerung in Home Assistant](https://youtu.be/aCKLKGYiA7w)
+
+Please note that all these videos are **not** created by the developer of this component and therefore may by outdated, point in the wrong direction or contain errors. If you have questions, please create an issue here on github. Do not ask your question in the YouTube comments because you may get wrong answers there.

doc/source/abfall_zollernalbkreis_de.md

@@ -2,8 +2,6 @@
 
 Support for schedules provided by [https://www.abfallkalender-zak.de/](https://www.abfallkalender-zak.de/).
 
-
-
 ## Configuration via configuration.yaml
 
 ```yaml
@@ -61,8 +59,6 @@ waste_collection_schedule:
 
 ## How to get the source arguments
 
-
-
 ### Hardcore Variant: Extract arguments from website
 
 Another way get the source arguments is to extract the arguments from the website using a (desktop) browser with developer tools, e.g. Google Chrome:

doc/source/aucklandcouncil_govt_nz.md

@@ -9,7 +9,7 @@ waste_collection_schedule:
   sources:
     - name: aucklandcouncil_govt_nz
       args:
-        area_number: AREA_NUMBER_FROM_COLLECTION_PAGE # see 'How to get the source argumnet below'
+        area_number: AREA_NUMBER_FROM_COLLECTION_PAGE # see 'How to get the source argument below'
 ```
 
 ### Configuration Variables
@@ -28,7 +28,9 @@ waste_collection_schedule:
 ```
 
 ## How to get the source argument
+
 The source argument is the area number from Auckland Council site:
-  -  Open your collection days page by  entering your address [on the Auckland Council collection day finder](https://www.aucklandcouncil.govt.nz/rubbish-recycling/rubbish-recycling-collections/Pages/rubbish-recycling-collection-days.aspx)
+
-  -  Look for 'an' parameter in your browser URL, e.g. https://www.aucklandcouncil.govt.nz/rubbish-recycling/rubbish-recycling-collections/Pages/collection-day-detail.aspx?an=12342306525
+-  Open your collection days page by  entering your address [on the Auckland Council collection day finder](https://www.aucklandcouncil.govt.nz/rubbish-recycling/rubbish-recycling-collections/Pages/rubbish-recycling-collection-days.aspx)
-    - In this example the area number is 12342306525 .
+- Look for 'an' parameter in your browser URL, e.g. https://www.aucklandcouncil.govt.nz/rubbish-recycling/rubbish-recycling-collections/Pages/collection-day-detail.aspx?an=12342306525
+- In this example the area number is `12342306525`.

doc/source/awido_de.md

@@ -47,6 +47,7 @@ waste_collection_schedule:
 ### customer
 
 List of customers (2021-07-09):
+
 - `rmk`: AWG des Rems-Murr-Kreises mbH
 - `lra-schweinfurt`: Landkreis Schweinfurt
 - `gotha`: Landkreis Gotha

doc/source/awr_de.md

@@ -12,6 +12,7 @@ waste_collection_schedule:
         city: CITY
         street: STREET
 ```
+
 ### Configuration Variables
 
 **city**<br>

doc/source/awsh_de.md

@@ -12,6 +12,7 @@ waste_collection_schedule:
         city: CITY
         street: STREET
 ```
+
 ### Configuration Variables
 
 **city**<br>

doc/source/brisbane_qld_gov_au.md

@@ -40,4 +40,3 @@ waste_collection_schedule:
 ## How to get the source arguments
 
 Visit the [Brisbane City Council bin collection calendar](https://www.brisbane.qld.gov.au/clean-and-green/rubbish-tips-and-bins/rubbish-collections/bin-collection-calendar) page and search for your address.  The arguments should exactly match the results shown for Suburb and Street and the number portion of the Property.
-

doc/source/ccc_govt_nz.md

@@ -26,6 +26,7 @@ waste_collection_schedule:
       args:
         address: "53 Hereford Street"
 ```
+
 ## Bin Colours example - Red, Yellow & Green
 
 ```yaml

doc/source/ics.md

@@ -5,9 +5,11 @@ Add support for schedules from ICS / iCal files. Files can be either stored in a
 This source has been successfully tested with the following service providers:
 
 ### Belgium
+
 - [Limburg.net](https://www.limburg.net/afvalkalender) ([Example](#limburg-net))
 
 ### Germany
+
 - [Abfall Landkreis Stade](https://abfall.landkreis-stade.de/)
 - [Abfallkalender Zollernalbkreis](https://www.zollernalbkreis.de/landratsamt/aemter++und+organisation/Elektronischer+Abfallkalender) ([Example](#abfallkalender-zollernalbkreis))
 - [Abfallwirtschaft Kreis Böblingen](https://www.lrabb.de/start/Service+_+Verwaltung/Abfuhrtermine.html)
@@ -24,11 +26,12 @@ This source has been successfully tested with the following service providers:
 - [Stadtreinigung Leipzig](https://www.stadtreinigung-leipzig.de/)
 
 ### Sweden
+
 - [NSR Nordvästra Skåne](https://nsr.se/privat/allt-om-din-sophamtning/nar-toms-mitt-karl/tomningskalender/)
 
 ### United States of America
 - [ReCollect.net](https://recollect.net) ([Notes](#recollect))
-- [Western Disposal Residental (Colorado)](https://www.westerndisposal.com/residential/) (Unofficial, [Notes](#western-disposal-colorado))
+- [Western Disposal Residential (Colorado)](https://www.westerndisposal.com/residential/) (Unofficial, [Notes](#western-disposal-colorado))
 
 ## Configuration via configuration.yaml
 
@@ -79,7 +82,13 @@ Need to be `GET` or `POST`.
 **params**<br>
 *(dict) (optional, default: None)*
 
-Dictionary, list of tuples or bytes to send in the query string for the HTTP request. This gets urlencoded and either attached to the raw URL when GET method is used or send with `Content-Type: application/x-www-form-urlencoded` and a automaticly generated `Content-Length` header as POST method HTTP body. Only used if `url` is specified, not used for `file`.
+Dictionary, list of tuples or bytes to send in the query string for the HTTP request.
+
+This gets
+- urlencoded and either attached to the raw URL when GET method is used.
+- send with `Content-Type: application/x-www-form-urlencoded` and an automatically generated `Content-Length` header as POST method HTTP body.
+
+Only used if `url` is specified, not used for `file`.
 
 **year_field**<br>
 *(string) (optional, default: None)*
@@ -237,7 +246,7 @@ waste_collection_schedule:
 ### Limburg.net
 
 This tool works for all municipalities of the province of Limburg and the municipality of Diest.<br>
-Find your ICS export link via the calender page - enter your address so that the system can look up the necessary data for your city and street to construct the URL.<br><br>
+Find your ICS export link via the calendar page - enter your address so that the system can look up the necessary data for your city and street to construct the URL.<br><br>
 Generating the URL on the site of Limburg.net is the simplest.
 
 ```yaml
@@ -308,4 +317,3 @@ waste_collection_schedule:
         - type: Wednesday E Recycling
           alias: Recycling
 ```
-

doc/source/jumomind_de.md

@@ -44,5 +44,3 @@ There is a script with an interactive command line interface which generates the
 [https://github.com/mampfes/hacs_waste_collection_schedule/blob/master/custom_components/waste_collection_schedule/waste_collection_schedule/wizard/jumomind_de.py](https://github.com/mampfes/hacs_waste_collection_schedule/blob/master/custom_components/waste_collection_schedule/waste_collection_schedule/wizard/jumomind_de.py).
 
 First, install the Python module `inquirer`. Then run this script from a shell and answer the questions.
-
-

doc/source/kwb_goslar_de.md

@@ -18,6 +18,7 @@ waste_collection_schedule:
 *(string) (required)*
 
 #### How to find the `pois` value
+
 1. Open [Online-Abfuhrkalender 2022](https://www.kwb-goslar.de/Abfallwirtschaft/Abfuhr/Online-Abfuhrkalender-2022/) (`Abfallwirtschaft -> Abfuhr -> Online-Abfuhrkalender 2022`)
 2. Select your city (`Ort auswählen`)
 3. Select your district/street (`Ortsteil, Straße auswählen`)

doc/source/lindau_ch.md

@@ -19,6 +19,7 @@ waste_collection_schedule:
 *(string) (required)*
 
 Choose one of the following list:
+
 - Grafstal
 - Lindau
 - Tagelswangen

doc/source/nawma_sa_gov_au.md

@@ -44,4 +44,3 @@ waste_collection_schedule:
 Visit the [North Adelaide Waste Management Authority collection days](https://www.nawma.sa.gov.au/kerbside-collections/bin-collection-days/) page and search for your address.  The arguments should exactly match the results shown for Suburb and Street and (if required) the number portion of the auto-completed address.
 
 Note: Some addresses can be quite obscure, for example for the Gawler main street set `street_name` to `'Murray Street (sec between Ayers and the railway line'`.
-

doc/source/rh_entsorgung_de.md

@@ -59,7 +59,8 @@ These values are the location you want to query for. Make sure, the writing is e
 ### garbage_types
 
 Garbage types are mapped as follows:
-```
+
+```text
 1: Restmülltonne
 2: Biotonne
 3: Papiertonne

doc/source/sector27_de.md

@@ -1,6 +1,7 @@
 # Sector27.de
 
 Support for schedules provided by [Sector27.de](https://muellkalender.sector27.de). This service is used by the following cities:
+
 - Datteln
 - Marl
 - Oer-Erkenschwick

doc/source/was_wolfsburg_de.md

@@ -23,7 +23,6 @@ waste_collection_schedule:
 **street**<br>
 *(string) (required)*
 
-
 ## Example
 
 ```yaml

doc/source/ximmio_nl.md

@@ -35,7 +35,6 @@ Use one of the following codes as company code:
 - waardlanden
 - ximmio
 
-
 **post_code**<br>
 *(string) (required)*
 

info.md

@@ -46,8 +46,10 @@ Currently the following service providers are supported:
 - [Stonnington City Council, Melbourne](https://github.com/mampfes/hacs_waste_collection_schedule/blob/master/doc/source/stonnington_vic_gov_au.md)
 
 ### Belgium
+
 - [Hygea](https://github.com/mampfes/hacs_waste_collection_schedule/blob/master/doc/source/hygea_be.md)
 - [Recycle! / RecycleApp.be](https://github.com/mampfes/hacs_waste_collection_schedule/blob/master/doc/source/recycleapp_be.md)
+
 ### Germany
 
 - [Abfall.IO / AbfallPlus.de](https://github.com/mampfes/hacs_waste_collection_schedule/blob/master/doc/source/abfall_io.md)
@@ -85,10 +87,12 @@ Currently the following service providers are supported:
 - [Gore, Invercargill & Southland](https://github.com/mampfes/hacs_waste_collection_schedule/blob/master/doc/source/wastenet_org_nz.md)
 
 ### Sweden
+
 - [Lerum.se](https://github.com/mampfes/hacs_waste_collection_schedule/blob/master/doc/source/lerum_se.md)
 - [Sysav.se](https://github.com/mampfes/hacs_waste_collection_schedule/blob/master/doc/source/sysav_se.md)
 
 ### Switzerland
+
 - [Lindau.ch](https://github.com/mampfes/hacs_waste_collection_schedule/blob/master/doc/source/lindau_ch.md)
 
 ### United States of America