documenting to_seconds filter (#4203)

* documenting to_seconds filter

example of documenting filters when multiple exist inside one file

* Update to_seconds.yml

* Apply suggestions from code review

* Extend documentation. Add BOTMETA entry.

Co-authored-by: Felix Fontein <felix@fontein.de>

.github/BOTMETA.yml

@@ -140,6 +140,8 @@ files:
     maintainers: resmo
   $filters/unicode_normalize.py:
     maintainers: Ajpantuso
+  $filters/to_seconds.yml:
+    maintainers: resmo
   $filters/version_sort.py:
     maintainers: ericzolf
   $inventories/:

plugins/filter/to_seconds.yml

@@ -0,0 +1,40 @@
+DOCUMENTATION:
+  name: community.general.to_seconds
+  short_description: Converte a date/time string to seconds
+  version_added: 0.2.0
+  description:
+    - Parse a human readable time string and convert to seconds.
+  options:
+    _input:
+      description:
+        - The time string to convert.
+        - Can use the units C(y) and C(year) for a year, C(mo) and C(month) for a month, C(w) and C(week) for a week,
+          C(d) and C(day) for a day, C(h) and C(hour) for a hour, C(m), C(min) and C(minute) for minutes, C(s), C(sec)
+          and C(second) for seconds, C(ms), C(msec), C(msecond) and C(millisecond) for milliseconds. The suffix C(s)
+          can be added to a unit as well, so C(seconds) is the same as C(second).
+        - Valid strings are space separated combinations of an integer with an optional minus sign and a unit.
+        - Examples are C(1h), C(-5m), and C(3h -5m 6s).
+      type: string
+      required: true
+    year:
+      description:
+        - Number of days per year.
+      default: 365
+      type: float
+    month:
+      description:
+        - Number of days per month.
+      default: 30
+      type: float
+  authors:
+    - René Moser (@resmo)
+
+EXAMPLES: |
+  - name: Convert a duration into seconds
+    debug:
+      msg: "{{ '30h 20m 10s 123ms' | community.general.to_seconds }}"
+
+RETURN:
+  _value:
+    description: Number of seconds.
+    type: float