homebrew_cask: Update documentation and examples (#66073)

* properly document ``upgrade`` option as an alias to ``upgrade_all``, and not a separate option
* Update documentation.
* Update examples.

Fixes: #34696

Signed-off-by: Abhijeet Kasurde <akasurde@redhat.com>
This commit is contained in:
Abhijeet Kasurde 2019-12-27 10:08:18 +05:30 committed by GitHub
parent 82c63c0ac3
commit 4d1a57453e
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
2 changed files with 92 additions and 83 deletions

View file

@ -1,8 +1,8 @@
#!/usr/bin/python #!/usr/bin/python
# -*- coding: utf-8 -*- # -*- coding: utf-8 -*-
# (c) 2013, Daniel Jaouen <dcj24@cornell.edu> # Copyright: (c) 2013, Daniel Jaouen <dcj24@cornell.edu>
# (c) 2016, Indrajit Raychaudhuri <irc+code@indrajit.com> # Copyright: (c) 2016, Indrajit Raychaudhuri <irc+code@indrajit.com>
# #
# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt) # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
@ -10,131 +10,143 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type __metaclass__ = type
ANSIBLE_METADATA = {'metadata_version': '1.1', ANSIBLE_METADATA = {
'metadata_version': '1.1',
'status': ['preview'], 'status': ['preview'],
'supported_by': 'community'} 'supported_by': 'community'
}
DOCUMENTATION = ''' DOCUMENTATION = '''
--- ---
module: homebrew_cask module: homebrew_cask
author: author:
- "Indrajit Raychaudhuri (@indrajitr)" - "Indrajit Raychaudhuri (@indrajitr)"
- "Daniel Jaouen (@danieljaouen)" - "Daniel Jaouen (@danieljaouen)"
- "Enric Lluelles (@enriclluelles)" - "Enric Lluelles (@enriclluelles)"
requirements: requirements:
- "python >= 2.6" - "python >= 2.6"
short_description: Install/uninstall homebrew casks. short_description: Install and uninstall homebrew casks.
description: description:
- Manages Homebrew casks. - Manages Homebrew casks.
version_added: "1.6" version_added: "1.6"
options: options:
name: name:
description: description:
- name of cask to install/remove - Name of cask to install or remove.
required: true required: true
aliases: ['pkg', 'package', 'cask'] aliases: ['pkg', 'package', 'cask']
type: list
path: path:
description: description:
- "':' separated list of paths to search for 'brew' executable." - "':' separated list of paths to search for 'brew' executable."
default: '/usr/local/bin' default: '/usr/local/bin'
type: path
state: state:
description: description:
- state of the cask - State of the cask.
choices: [ 'present', 'absent', 'upgraded' ] choices: [ 'present', 'absent', 'upgraded' ]
default: present default: present
type: str
sudo_password: sudo_password:
description: description:
- The sudo password to be passed to SUDO_ASKPASS. - The sudo password to be passed to SUDO_ASKPASS.
required: false required: false
version_added: 2.8 version_added: 2.8
type: str
update_homebrew: update_homebrew:
description: description:
- update homebrew itself first. Note that C(brew cask update) is - Update homebrew itself first.
a synonym for C(brew update). - Note that C(brew cask update) is a synonym for C(brew update).
type: bool type: bool
default: 'no' default: 'no'
aliases: ['update-brew'] aliases: ['update-brew']
version_added: "2.2" version_added: "2.2"
install_options: install_options:
description: description:
- options flags to install a package - Options flags to install a package.
aliases: ['options'] aliases: ['options']
version_added: "2.2" version_added: "2.2"
type: list
accept_external_apps: accept_external_apps:
description: description:
- allow external apps - Allow external apps.
type: bool type: bool
default: 'no' default: 'no'
version_added: "2.5.0" version_added: "2.5.0"
upgrade_all: upgrade_all:
description: description:
- upgrade all casks (mutually exclusive with `upgrade`) - Upgrade all casks.
type: bool - Mutually exclusive with C(upgraded) state.
default: 'no'
version_added: "2.5.0"
upgrade:
description:
- upgrade all casks (mutually exclusive with `upgrade_all`)
type: bool type: bool
default: 'no' default: 'no'
version_added: "2.5.0" version_added: "2.5.0"
aliases: ['upgrade']
greedy: greedy:
description: description:
- upgrade casks that auto update; passes --greedy to brew cask - Upgrade casks that auto update.
outdated when checking if an installed cask has a newer version - Passes --greedy to brew cask outdated when checking
available if an installed cask has a newer version available.
type: bool type: bool
default: 'no' default: 'no'
version_added: "2.7.0" version_added: "2.7.0"
''' '''
EXAMPLES = ''' EXAMPLES = '''
- homebrew_cask: - name: Install cask
homebrew_cask:
name: alfred name: alfred
state: present state: present
- homebrew_cask: - name: Remove cask
homebrew_cask:
name: alfred name: alfred
state: absent state: absent
- homebrew_cask: - name: Install cask with install options
homebrew_cask:
name: alfred name: alfred
state: present state: present
install_options: 'appdir=/Applications' install_options: 'appdir=/Applications'
- homebrew_cask: - name: Install cask with install options
homebrew_cask:
name: alfred name: alfred
state: present state: present
install_options: 'debug,appdir=/Applications' install_options: 'debug,appdir=/Applications'
- homebrew_cask: - name: Allow external app
homebrew_cask:
name: alfred name: alfred
state: present state: present
accept_external_apps: True accept_external_apps: True
- homebrew_cask: - name: Remove cask with force option
homebrew_cask:
name: alfred name: alfred
state: absent state: absent
install_options: force install_options: force
- homebrew_cask: - name: Upgrade all casks
homebrew_cask:
upgrade_all: true upgrade_all: true
- homebrew_cask: - name: Upgrade given cask with force option
homebrew_cask:
name: alfred name: alfred
state: upgraded state: upgraded
install_options: force install_options: force
- homebrew_cask: - name: Upgrade cask with greedy option
homebrew_cask:
name: 1password name: 1password
state: upgraded state: upgraded
greedy: True greedy: True
- homebrew_cask: - name: Using sudo password for installing cask
homebrew_cask:
name: wireshark name: wireshark
state: present state: present
sudo_password: "{{ ansible_become_pass }}" sudo_password: "{{ ansible_become_pass }}"
''' '''
import os import os

View file

@ -5097,11 +5097,8 @@ lib/ansible/modules/packaging/os/homebrew.py validate-modules:doc-missing-type
lib/ansible/modules/packaging/os/homebrew.py validate-modules:parameter-invalid lib/ansible/modules/packaging/os/homebrew.py validate-modules:parameter-invalid
lib/ansible/modules/packaging/os/homebrew.py validate-modules:parameter-type-not-in-doc lib/ansible/modules/packaging/os/homebrew.py validate-modules:parameter-type-not-in-doc
lib/ansible/modules/packaging/os/homebrew_cask.py validate-modules:doc-choices-do-not-match-spec lib/ansible/modules/packaging/os/homebrew_cask.py validate-modules:doc-choices-do-not-match-spec
lib/ansible/modules/packaging/os/homebrew_cask.py validate-modules:doc-missing-type
lib/ansible/modules/packaging/os/homebrew_cask.py validate-modules:doc-required-mismatch lib/ansible/modules/packaging/os/homebrew_cask.py validate-modules:doc-required-mismatch
lib/ansible/modules/packaging/os/homebrew_cask.py validate-modules:parameter-documented-multiple-times
lib/ansible/modules/packaging/os/homebrew_cask.py validate-modules:parameter-invalid lib/ansible/modules/packaging/os/homebrew_cask.py validate-modules:parameter-invalid
lib/ansible/modules/packaging/os/homebrew_cask.py validate-modules:parameter-type-not-in-doc
lib/ansible/modules/packaging/os/homebrew_tap.py validate-modules:doc-missing-type lib/ansible/modules/packaging/os/homebrew_tap.py validate-modules:doc-missing-type
lib/ansible/modules/packaging/os/homebrew_tap.py validate-modules:parameter-type-not-in-doc lib/ansible/modules/packaging/os/homebrew_tap.py validate-modules:parameter-type-not-in-doc
lib/ansible/modules/packaging/os/layman.py validate-modules:doc-missing-type lib/ansible/modules/packaging/os/layman.py validate-modules:doc-missing-type