Merge pull request #8 from panchoh/simplify-setup-instructions

README.md: Simplify setup instructions

README.md

@@ -6,20 +6,19 @@ The following helpers are supported and automatically selected in the order they
 - [pacaur](https://github.com/rmarquis/pacaur)
 - [trizen](https://github.com/trizen/trizen)
 - [pikaur](https://github.com/actionless/pikaur)
-- [yaourt](https://github.com/archlinuxfr/yaourt)
 - [yay](https://github.com/Jguer/yay)
 
 makepkg will be used if no helper was found or if it's specified explicitly.
 - [makepkg](https://wiki.archlinux.org/index.php/makepkg)
 
 ## Options
-|parameter      |required |default |choices                                                      |comments|
+|parameter      |required |default |choices                                            |comments|
-|---            |---      |---     |---                                                          |---|
+|---            |---      |---     |---                                                |---|
-|name           |no       |        |                                                             |Name or list of names of the package(s) to install or upgrade.|
+|name           |no       |        |                                                   |Name or list of names of the package(s) to install or upgrade.|
-|upgrade        |no       |no      |yes, no                                                      |Whether or not to upgrade whole system.|
+|upgrade        |no       |no      |yes, no                                            |Whether or not to upgrade whole system.|
-|use            |no       |auto    |auto, aurman, pacaur, trizen, pikaur, yaourt, yay, makepkg  |The helper to use, 'auto' uses the first known helper found and makepkg as a fallback.|
+|use            |no       |auto    |auto, aurman, pacaur, trizen, pikaur, yay, makepkg |The helper to use, 'auto' uses the first known helper found and makepkg as a fallback.|
-|skip_installed |no       |no      |yes, no                                                      |Skip operations if the package is present.|
+|skip_installed |no       |no      |yes, no                                            |Skip operations if the package is present.|
-|skip_pgp_check |no       |no      |yes, no                                                      |Skip verification of PGP signatures. This is useful when installing packages on a host without GnuPG (properly) configured. Only valid with makepkg.|
+|skip_pgp_check |no       |no      |yes, no                                            |Skip verification of PGP signatures. This is useful when installing packages on a host without GnuPG (properly) configured. Only valid with makepkg.|
 
 ### Note
 * Either *name* or *upgrade* is required, both cannot be used together.
@@ -27,16 +26,14 @@ makepkg will be used if no helper was found or if it's specified explicitly.
 * In the *use*=*auto* mode, makepkg is used as a fallback if no known helper is found.
 
 ## Installing
-1. Clone the *ansibe-aur* repository in your playbook custom-module directory:
+### aur-ansible-git AUR package
-```
+The [aur-ansible-git](https://aur.archlinux.org/packages/ansible-aur-git) package is available in the AUR.
-mkdir --parents library
+Note the module is installed in `/usr/share/ansible/plugins/modules` which is one of the default module library paths.
-cd library
-git clone git@github.com:kewlfft/ansible-aur.git
-```
 
-2. Link the script to `library/aur`:
+### Manual installation
+Just clone the *ansible-aur* repository into your user custom-module directory:
 ```
-ln --symbolic ansible-aur/aur.py aur
+git clone https://github.com/kewlfft/ansible-aur.git ~/.ansible/plugins/modules/aur
 ```
 
 ## Usage

aur.py

@@ -1,4 +1,6 @@
-#!/usr/bin/env python
+#!/usr/bin/python
+
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
 
 from ansible.module_utils.basic import *
 from ansible.module_utils.urls import open_url
@@ -9,6 +11,64 @@ import os.path
 import tempfile
 
 
+DOCUMENTATION = '''
+---
+module: aur
+short_description: Manage packages from the AUR
+description:
+    - Manage packages from the Arch User Repository (AUR)
+author:
+    - Kewl <xrjy@nygb.rh.bet(rot13)>
+options:
+    name:
+        description:
+            - Name or list of names of the package(s) to install or upgrade.
+
+    upgrade:
+        description:
+            - Whether or not to upgrade whole system.
+        type: bool
+        default: no
+
+    use:
+        description:
+            - The helper to use, 'auto' uses the first known helper found and makepkg as a fallback.
+        default: auto
+        choices: [ auto, aurman, pacaur, trizen, pikaur, yay, makepkg ]
+
+    skip_installed:
+        description:
+            - Skip operations if the package is present.
+        type: bool
+        default: no
+
+    skip_pgp_check:
+        description:
+            - Skip verification of PGP signatures.
+              This is useful when installing packages on a host without GnuPG (properly) configured.
+              Only valid with makepkg.
+        type: bool
+        default: no
+notes:
+  - When used with a `loop:` each package will be processed individually,
+    it is much more efficient to pass the list directly to the `name` option.
+'''
+
+RETURN = '''
+msg:
+    description: action that has been taken
+helper:
+    the helper that was actually used
+'''
+
+EXAMPLES = '''
+- name: Install trizen using makepkg, skip if trizen is already installed
+  aur: name=trizen use=makepkg skip_installed=true
+  become: yes
+  become_user: aur_builder
+'''
+
+
 def_lang = ['env', 'LC_ALL=C']
 
 use_cmd = {
@@ -16,7 +76,6 @@ use_cmd = {
     'pacaur': ['pacaur', '-S', '--noconfirm', '--noedit', '--needed'],
     'trizen': ['trizen', '-S', '--noconfirm', '--noedit', '--needed'],
     'pikaur': ['pikaur', '-S', '--noconfirm', '--noedit', '--needed'],
-    'yaourt': ['yaourt', '-S', '--noconfirm', '--needed'],
     'yay': ['yay', '-S', '--noconfirm'],
     'makepkg': ['makepkg', '--syncdeps', '--install', '--noconfirm', '--needed']
 }