document some 'dir' based filters (#77687)

Co-authored-by: flowerysong <junk+github@flowerysong.com>
Co-authored-by: Emmanuel Ugwu <32464178+ugwutotheeshoes@users.noreply.github.com>

lib/ansible/plugins/filter/basename.yml

@@ -0,0 +1,24 @@
+DOCUMENTATION:
+  name: basename
+  author: ansible core team
+  version_added: "historical"
+  short_description: get a path's base name
+  description:
+    - Returns the last name component of a path, what is left in the string that is not 'dirname'.
+  options:
+    _input:
+      description: A path
+      type: path
+      required: true
+  seealso:
+    - plugin_type: filter
+      plugin: ansible.builtin.dirname
+EXAMPLES: |
+
+  # To get the last name of a file path, like 'foo.txt' out of '/etc/asdf/foo.txt'
+  {{ mypath | basename }}
+
+RETURN:
+  _value:
+    description: The base name from the path provided.
+    type: str

lib/ansible/plugins/filter/dirname.yml

@@ -0,0 +1,24 @@
+DOCUMENTATION:
+  name: dirname
+  author: ansible core team
+  version_added: "historical"
+  short_description: get a path's directory name
+  description:
+    - Returns the 'head' component of a path, basically everything that is not the 'basename'.
+  options:
+    _input:
+      description: A path
+      type: path
+      required: true
+  seealso:
+    - plugin: ansible.builtin.basename
+      plugin_type: filter
+EXAMPLES: |
+
+  # To get the dir name of a file path, like '/etc/asdf' out of '/etc/asdf/foo.txt'
+  {{ mypath | dirname }}
+
+RETURN:
+  _value:
+    description: The directory portion of the original path.
+    type: path

lib/ansible/plugins/filter/expanduser.yml

@@ -0,0 +1,21 @@
+DOCUMENTATION:
+  name: basename
+  author: ansible core team
+  version_added: "1.5"
+  short_description: Returns a path with '~' translation.
+  description:
+    - Translates `~` in a path to the proper user's home directory.
+  options:
+    _input:
+      description: A string that contains a path.
+      type: path
+      required: true
+EXAMPLES: |
+
+  # To get '/home/myuser/stuff.txt' from '~/stuff.txt'.
+  {{ mypath | expanduser }}
+
+RETURN:
+  _value:
+    description: The translated path.
+    type: path

lib/ansible/plugins/filter/expandvars.yml

@@ -0,0 +1,21 @@
+DOCUMENTATION:
+  name: expandvars
+  author: ansible core team
+  version_added: "1.5"
+  short_description: expand environment variables
+  description:
+    - Will do a shell-like substitution of environment variables on the provided input.
+  options:
+    _input:
+      description: A string that contains environment variables.
+      type: str
+      required: true
+EXAMPLES: |
+
+  # To get '/home/myuser/stuff.txt' from '$HOME/stuff.txt'
+  {{ mypath | expandvars }}
+
+RETURN:
+  _value:
+    description: The string with translated environment variable values.
+    type: str