From 378b20ac3258a7624a4054d6999ede29bca30ce4 Mon Sep 17 00:00:00 2001
From: Brian Coca <bcoca@users.noreply.github.com>
Date: Wed, 27 Apr 2022 16:39:36 -0400
Subject: [PATCH] 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           |  2 ++
 plugins/filter/to_seconds.yml | 40 +++++++++++++++++++++++++++++++++++
 2 files changed, 42 insertions(+)
 create mode 100644 plugins/filter/to_seconds.yml

diff --git a/.github/BOTMETA.yml b/.github/BOTMETA.yml
index 199ca9e4d1..0e32ec64b4 100644
--- a/.github/BOTMETA.yml
+++ b/.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/:
diff --git a/plugins/filter/to_seconds.yml b/plugins/filter/to_seconds.yml
new file mode 100644
index 0000000000..af6ae82b09
--- /dev/null
+++ b/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