Merge pull request #1152 from sfromm/moduledocs

Add module documentation for git, group, service, and user
This commit is contained in:
Michael DeHaan 2012-09-30 04:56:37 -07:00
commit b7571f56c2
4 changed files with 210 additions and 0 deletions

42
git
View file

@ -18,6 +18,48 @@
# You should have received a copy of the GNU General Public License # You should have received a copy of the GNU General Public License
# along with Ansible. If not, see <http://www.gnu.org/licenses/>. # along with Ansible. If not, see <http://www.gnu.org/licenses/>.
DOCUMENTATION = '''
---
module: git
author: Michael DeHaan
version_added: 0.0.1
short_description: Deploy software (or files) from git checkouts
description:
- Manage git checkouts of repositories to deploy files or software.
options:
repo:
required: true
aliases: [ name ]
description:
- git, ssh, or http protocol address of the git repository.
dest:
required: true
description:
- Absolute path of where the repository should be checked out to.
version:
required: false
default: "HEAD"
description:
- What version of the repository to check out. This can be the
git I(SHA), the literal string I(HEAD), branch name, or a tag name.
remote:
required: false
default: "origin"
description:
- Name of the remote branch.
force:
required: false
default: "yes"
choices: [ yes, no ]
description:
- (New in 0.7) If yes, any modified files in the working
repository will be discarded. Prior to 0.7, this was always
'yes' and could not be disabled.
examples:
- code: git repo=git://foosball.example.org/path/to/repo.git dest=/srv/checkout version=release-0.22
description: Example git checkout from Ansible Playbooks
'''
import re import re
import tempfile import tempfile

36
group
View file

@ -18,6 +18,42 @@
# You should have received a copy of the GNU General Public License # You should have received a copy of the GNU General Public License
# along with Ansible. If not, see <http://www.gnu.org/licenses/>. # along with Ansible. If not, see <http://www.gnu.org/licenses/>.
DOCUMENTATION = '''
---
module: group
author: Stephen Fromm
version_added: 0.0.2
short_description: Add or remove groups
requirements: [ groupadd, groupdel, groupmod ]
description:
- Manage presence of groups on a host.
options:
name:
required: true
description:
- Name of the group to manage.
gid:
required: false
description:
- Optional I(GID) to set for the group.
state:
required: false
default: "present"
choices: [ present, absent ]
description:
- Whether the group should be present or not on the remote host.
system:
required: false
default: "no"
choices: [ yes, no ]
description:
- If I(yes), indicates that the group created is a system group.
examples:
- code: group name=somegroup state=present
description: Example group command from Ansible Playbooks
'''
import grp import grp
def group_del(module, group): def group_del(module, group):

45
service
View file

@ -18,6 +18,51 @@
# You should have received a copy of the GNU General Public License # You should have received a copy of the GNU General Public License
# along with Ansible. If not, see <http://www.gnu.org/licenses/>. # along with Ansible. If not, see <http://www.gnu.org/licenses/>.
DOCUMENTATION = '''
---
module: service
author: Michael DeHaan
version_added: 0.0.1
short_description: Manage services.
description:
- Controls services on remote hosts.
options:
name:
required: true
description: Name of the service.
state:
required: false
choices: [ running, started, stopped, restarted, reloaded ]
description: I(started), I(stopped), I(reloaded), I(restarted).
I(Started)/I(stopped) are idempotent actions that will
not run commands unless necessary. I(restarted) will
always bounce the service. I(reloaded) will always
reload.
pattern:
required: false
description: New in 0.7. If the service does not respond to the
status command, name a substring to look for as would
be found in the output of the I(ps) command
as a stand-in for a status result. If the string is
found, the servie will be assumed to be running.
enabled:
required: false
choices: [ yes, no ]
description: Whether the service should start on boot. Either
I(yes) or I(no).
examples:
- code: service name=httpd state=started
description: Example action from Ansible Playbooks
- code: service name=httpd state=stopped
description: Example action from Ansible Playbooks
- code: service name=httpd state=restarted
description: Example action from Ansible Playbooks
- code: service name=httpd state=reloaded
description: Example action from Ansible Playbooks
- code: service name=foo pattern=/usr/bin/foo state=started
description: Example action from Ansible Playbooks
'''
import platform import platform
SERVICE = None SERVICE = None

87
user
View file

@ -18,6 +18,93 @@
# You should have received a copy of the GNU General Public License # You should have received a copy of the GNU General Public License
# along with Ansible. If not, see <http://www.gnu.org/licenses/>. # along with Ansible. If not, see <http://www.gnu.org/licenses/>.
DOCUMENTATION = '''
---
module: user
author: Stephen Fromm
version_added: 0.0.2
short_description: Manage user accounts
requirements: [ useradd, userdel, usermod ]
description:
- Manage user accounts and user attributes.
options:
name:
required: true
description:
- Name of the user to create, remove or modify.
comment:
required: false
description:
- Optionally sets the description (aka I(GECOS)) of user account.
uid:
required: false
description:
- Optionally sets the I(UID) of the user.
group:
required: false
description:
- Optionally sets the user's primary group (takes a group name).
groups:
required: false
description:
- Puts the user in this comma-delimited list of groups.
append:
required: false
description:
- If I(yes), will only add groups, not set them to just the list
in I(groups).
shell:
required: false
description:
- Optionally set the user's shell.
home:
required: false
description:
- Optionally set the user's home directory.
password:
required: false
description:
- Optionally set the user's password to this crypted value. See
the user example in the github examples directory for what this looks
like in a playbook.
state:
required: false
default: "present"
choices: [ present, absent ]
description:
- Whether the account should exist. When I(absent), removes
the user account.
createhome:
required: false
default: "yes"
choices: [ yes, no ]
description:
- Unless set to I(no), a home directory will be made for the user
when the account is created.
system:
required: false
default: "no"
choices: [ yes, no ]
description:
- When creating an account, setting this to I(yes) makes the user a
system account. This setting cannot be changed on existing users.
force:
required: false
default: "no"
choices: [ yes, no ]
description:
- When used with I(state=absent), behavior is as with
I(userdel --force).
remove:
required: false
default: "no"
choices: [ yes, no ]
description:
- When used with I(state=absent), behavior is as with
I(userdel --remove).
'''
import os import os
import pwd import pwd
import grp import grp