Merge pull request #1152 from sfromm/moduledocs

Add module documentation for git, group, service, and user

library/git

@@ -18,6 +18,48 @@
 # You should have received a copy of the GNU General Public License
 # 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 tempfile
 

library/group

@@ -18,6 +18,42 @@
 # You should have received a copy of the GNU General Public License
 # 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
 
 def group_del(module, group):

library/service

@@ -18,6 +18,51 @@
 # You should have received a copy of the GNU General Public License
 # 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
 
 SERVICE = None

library/user

@@ -18,6 +18,93 @@
 # You should have received a copy of the GNU General Public License
 # 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 pwd
 import grp