docs: Update docs and refactor doc to docs

README.md

@@ -1,15 +1,14 @@
 # Ansible KeePass Lookup Plugin
 
-This collection provides a plugin that allows to read data from KeePass file (modifying is not supported)
+This collection provides plugins that allows to read data from KeePass file (modifying is not supported)
 
 ## How it works
 
-The plugin opens a UNIX socket with decrypted KeePass file. 
+The lookup plugin opens a UNIX socket with decrypted KeePass file. 
 For performance reasons, decryption occurs only once at socket startup, 
 and the KeePass file remains decrypted as long as the socket is open.
 The UNIX socket file is stored in a temporary folder according to OS.
 
-
 ## Installation
 
 Requirements: `python 3`, `pykeepass==4.0.3`
@@ -47,5 +46,17 @@ Use `ansible-vault encrypt_string` to encrypt it and use it like below
     ansible_become_pass      : "{{ lookup('viczem.keepass.keepass', 'path/to/entry', 'password') }}"
     custom_field             : "{{ lookup('viczem.keepass.keepass', 'path/to/entry', 'custom_properties', 'a_custom_property_name') }}"
     attachment               : "{{ lookup('viczem.keepass.keepass', 'path/to/entry', 'attachments', 'a_file_name') }}"
+    
+    - name: "Export file: attachment.txt"
+        viczem.keepass.attachment:
+          database: "{{ keepass_dbx }}"
+          password: "{{ keepass_psw }}"
+          entrypath: example/attachments
+          attachment: "attachment.txt"
+          dest: "{{ keepass_attachment_1_name }}"
 
-More examples see in [/doc/examples](/doc/examples).
+More examples see in [/docs/examples](/docs/examples).
+
+## Contributing
+
+See docs/contributing.

docs/contributing/README.md

@@ -0,0 +1,29 @@
+# Contributing
+
+1. Create ansible.cfg in cloned directory:
+
+```
+[defaults]
+COLLECTIONS_PATHS = ./collections
+```
+
+2. Create requirements.yml in cloned directory:
+
+```
+---
+collections:
+  - name: namespace.collection_name
+    source: /where/is/your/clone
+    type: dir
+```
+
+
+3. To install the collection _locally_ in your cloned directory, just install it through ansible-galaxy
+```shell
+rm -rf ./collections && ansible-galaxy install -r requirements.yml
+```
+
+Note: Any change on your clone imply to reinstall the collection.
+
+
+Tip: You can place a ansible.cfg with `COLLECTIONS_PATHS = ../../collections` in the examples dictory if you want to run the example on local collection in your cloned directory.

docs/examples/README.md

@@ -0,0 +1,5 @@
+# Example
+
+`ansible-playbook example-playbook.yml --ask-vault-pass -vvv`
+ 
+Password: `spamham`

docs/examples/example-playbook.yml

@@ -0,0 +1,54 @@
+---
+- name: Example
+  hosts: 127.0.0.1
+  connection: local
+  vars:
+    spam_login: "{{ lookup('viczem.keepass.keepass', 'spam', 'username') }}"
+    spam_password: "{{ lookup('viczem.keepass.keepass', 'spam', 'password') }}"
+    ham_login: "{{ lookup('viczem.keepass.keepass', 'example/ham', 'username') }}"
+    ham_password: "{{ lookup('viczem.keepass.keepass', 'example/ham', 'password') }}"
+    slash_login: "{{ lookup('viczem.keepass.keepass', 'slash\\/group/slash\\/title', 'username') }}"
+    slash_url: "{{ lookup('viczem.keepass.keepass', 'slash\\/group/slash\\/title', 'url') }}"
+    pork_custom_property: "{{ lookup('viczem.keepass.keepass', 'example/pork', 'custom_properties', 'pork_custom_property')}}"
+    attachment: "{{ lookup('viczem.keepass.keepass', 'example/pork', 'attachments', 'test.txt')}}"
+    keepass_attachment_1_name: "attachment_1.txt"
+    keepass_attachment_2_name: "attachment_2.zip"
+
+  tasks:
+    - debug:
+        msg: "fetch entry: '/spam'; username: '{{ spam_login }}'; password: '{{ spam_password }}'"
+
+    - debug:
+        msg: "fetch entry: '/examples/ham'; username: '{{ ham_login }}'; password: '{{ ham_password }}'"
+
+    - debug:
+        msg: "fetch entry: '/examples/port'; attachments: 'text.txt' -  '{{ attachment }}'"
+
+    - name: pause to emulate long time operation (greater than keepass_ttl)
+      pause:
+        seconds: 5
+
+    - debug:
+        msg: "fetch entry: '/examples/pork'; custom_properties: 'pork_custom_property' - '{{ pork_custom_property }}'"
+
+    - debug:
+        msg: "fetch entry: '/slash\\/group/slash\\/title'; username: '{{ slash_login }}'; url: '{{ slash_url }}'"
+
+    - debug: "{{ lookup('viczem.keepass.keepass', 'close') }}"
+
+    - name: "Export file: {{ keepass_attachment_1_name }}"
+      viczem.keepass.attachment:
+        database: "{{ keepass_dbx }}"
+        password: "{{ keepass_psw }}"
+        entrypath: example/attachments
+        attachment: "{{ keepass_attachment_1_name }}"
+        dest: "{{ keepass_attachment_1_name }}"
+
+    - name: "Export file: {{ keepass_attachment_2_name }}"
+      viczem.keepass.attachment:
+        database: "{{ keepass_dbx }}"
+        password: "{{ keepass_psw }}"
+        entrypath: example/attachments
+        attachment: "{{ keepass_attachment_2_name }}"
+        dest: "{{ keepass_attachment_2_name }}"
+        mode: 0600

docs/examples/group_vars/all

@@ -0,0 +1,9 @@
+keepass_ttl: 3
+keepass_dbx: "./example.kdbx"
+keepass_psw: !vault |
+          $ANSIBLE_VAULT;1.1;AES256
+          30656633313531336265353862356135373963636339376266373137376136636634393932623961
+          6138656232363861333932373066636237626232623566380a313964313733643532373139313636
+          62303365393630383037356334363332306239316566383061336263383134353139663161643331
+          3736316666613761380a646333353163633236323835313965313034373163343031616531393336
+          6538

galaxy.yml

@@ -21,11 +21,11 @@ authors:
 
 ### OPTIONAL but strongly recommended
 # A short summary description of the collection
-description: The collection provides a lookup plugin that allow to read data from KeePass file.
+description: The collection provides plugins that allow to read data from KeePass file.
 
 # Either a single license or a list of licenses for content inside of a collection. Ansible Galaxy currently only
 # accepts L(SPDX,https://spdx.org/licenses/) licenses. This key is mutually exclusive with 'license_file'
-license: []
+license: [MIT]
 
 # The path to the license file for the collection. This path is relative to the root of the collection. This key is
 # mutually exclusive with 'license'
@@ -36,6 +36,7 @@ license_file: 'LICENSE'
 tags:
   - keepass
   - lookup
+  - module
   - plugin
 
 # Collections that this collection requires to be installed for it to be usable. The key of the dict is the