fixup add specs/docs for filter plugins

Author: zstyblik

filter_plugins/core.py

@@ -47,15 +47,15 @@ def file_exists(stat_result):
 
 
 def parse_a2query(stdout):
-    """Parse out the first column from a2query STDOUT lines."""
+    """Parse the first column from a2query STDOUT lines."""
     if not stdout:
         return stdout
 
     return [line.split(" ")[0] for line in stdout]
 
 
 def to_vhost_filename(vhost):
-    """Turn vhost into filename."""
+    """Turn apache_vhost item(dict) into a filename."""
     try:
         priority = int(vhost.get("priority", 25))
         if "ssl" in vhost and vhost["ssl"]:

filter_plugins/file_exists.yml

@@ -0,0 +1,32 @@
+---
+DOCUMENTATION:
+  name: file_exists
+  version_added: "1.0"
+  short_description: evaluate results of stat
+  description:
+    - Evaluate results of ansible.builtin.stat.
+    - Returns True if file is either regular file or symlink.
+  positional: _input
+  options:
+    _input:
+      description: Value returned by ansible.builtin.stat.
+      type: dict
+      required: true
+
+EXAMPLES: |
+  - name: Check if SSL certificate exists
+    ansible.builtin.stat:
+      path: "/path/to/ssl.cert"
+    register: _stat_ssl_cert
+
+  - name: Does SSL cert file exist?
+    ansible.builtin.debug:
+      msg: "No, it does not"
+    when: >
+      _stat_ssl_cert is not defined
+      or _stat_ssl_cert | file_exists is false
+
+RETURN:
+  _value:
+    description: True if file is either regular file or symlink.
+    type: bool

filter_plugins/parse_a2query.yml

@@ -0,0 +1,24 @@
+---
+DOCUMENTATION:
+  name: parse_a2query
+  version_added: "1.0"
+  short_description: parse first column from a2query output
+  description:
+    - Parse the first column from a2query STDOUT lines.
+  positional: _input
+  options:
+    _input:
+      description: a2query's STDOUT.
+      type: str
+      required: true
+
+EXAMPLES: |
+  - name: Parse first column from a2query's stdout lines.
+    ansible.builtin.set_fact:
+      myvar: "{{ _apache_cmd_a2q.stdout_lines | parse_a2query }}"
+
+RETURN:
+  _value:
+    description: Fist column of a2query as a list.
+    type: list
+    elements: str

filter_plugins/to_vhost_filename.yml

@@ -0,0 +1,23 @@
+---
+DOCUMENTATION:
+  name: to_vhost_filename
+  version_added: "1.0"
+  short_description: turn apache_vhost item into filename.
+  description:
+    - Assemble filename(used to store vhost config) from item in apache_vhosts.
+  positional: _input
+  options:
+    _input:
+      description: apache_vhost item.
+      type: dict
+      required: true
+
+EXAMPLES: |
+  - name: Get virtual host's filename.
+    ansible.builtin.set_fact:
+      apache_vhost_filename: "{{ apache_vhosts[0] | to_vhost_filename }}"
+
+RETURN:
+  _value:
+    description: filename of given virtual host.
+    type: str