From e620fed755a9c7e07df846b7deb32bbbf3164ac7 Mon Sep 17 00:00:00 2001 From: Jan-Piet Mens Date: Mon, 1 Oct 2012 09:18:54 +0200 Subject: [PATCH] Jumbo DOCUMENTATION patch --- library/apt | 2 +- library/apt_repository | 2 +- library/authorized_key | 4 +-- library/command | 2 +- library/easy_install | 4 +-- library/facter | 5 ++-- library/file | 67 ++++++++++++++++++++++++++++++++++++++++-- library/lineinfile | 8 ++--- library/mysql_db | 10 +++++-- library/mysql_user | 10 +++++-- library/ohai | 4 ++- library/ping | 6 ++-- library/pip | 4 +-- library/postgresql_db | 4 +-- library/service | 32 ++++++++++---------- library/shell | 14 ++++++--- library/template | 3 +- library/user | 2 +- 18 files changed, 134 insertions(+), 49 deletions(-) diff --git a/library/apt b/library/apt index ed5420f3110..783f47be3f7 100755 --- a/library/apt +++ b/library/apt @@ -34,7 +34,7 @@ options: default: null state: description: - - Indicate the package state + - Indicate the desired package state required: false default: present choices: [ "installed", "latest", "remove", "absent", "present" ] diff --git a/library/apt_repository b/library/apt_repository index fef5d1df5c4..e33c1d36584 100755 --- a/library/apt_repository +++ b/library/apt_repository @@ -44,7 +44,7 @@ options: choices: [ "present", "absent" ] notes: - This module requires C(apt-add-repository) be available on destination server. To ensure this package is available use the C(apt) module and install the C(python-software-properties) package before using this module. - - This module works on Ubuntu and unstable Debian only, see *(https://github.com/ansible/ansible/pull/1082). + - This module works on Ubuntu and unstable Debian only, see U(https://github.com/ansible/ansible/pull/1082). - A bug in C(apt-add-repository) always adds C(deb) and C(deb-src) types for repositories (see the issue on Launchpad U(https://bugs.launchpad.net/ubuntu/+source/software-properties/+bug/987264)), if some repo don't have source (eg MongoDB repo from 10gen) the system fails while updating repositories. author: Matt Wright examples: diff --git a/library/authorized_key b/library/authorized_key index 1353459530b..70cc1579870 100755 --- a/library/authorized_key +++ b/library/authorized_key @@ -24,9 +24,9 @@ along with Ansible. If not, see . DOCUMENTATION = ''' --- module: authorized_key -short_description: Adds or removes an authorized key for a user from a remote host. +short_description: Adds or removes an SSH authorized key description: - - Adds or removes an authorized key for a user from a remote host. + - Adds or removes an SSH authorized key for a user from a remote host. version_added: "0.5" options: user: diff --git a/library/command b/library/command index 61d78ec5632..e84f74451a7 100755 --- a/library/command +++ b/library/command @@ -31,7 +31,7 @@ DOCUMENTATION = ''' module: command short_description: Executes a command on a remote node description: - - The command module takes the command name followed by a list of arguments, space delimited. + - The command module takes the command name followed by a list of space-delimited arguments. - The given command will be executed on all selected nodes. It will not be processed through the shell, so variables like C($HOME) and operations like C("<"), C(">"), C("|"), and C("&") will not work. As such, all diff --git a/library/easy_install b/library/easy_install index bd2161c3267..22910f8fa20 100755 --- a/library/easy_install +++ b/library/easy_install @@ -43,9 +43,9 @@ examples: - code: easy_install name=pip description: "Examples from Ansible Playbooks" - code: easy_install name=flask virtualenv=/webapps/myapp/venv - description: "Install I(flask) into the specified I(virtualenv)" + description: "Install I(Flask) (U(http://flask.pocoo.org/)) into the specified I(virtualenv)" notes: - - Please note that the M(easy_install) command can only install Python + - Please note that the M(easy_install) module can only install Python libraries. Thus this module is not able to remove libraries. It is generally recommended to use the M(pip) module which you can first install using M(easy_install). diff --git a/library/facter b/library/facter index e4baac035e4..b4975d606e8 100755 --- a/library/facter +++ b/library/facter @@ -25,8 +25,9 @@ DOCUMENTATION = ''' module: facter short_description: Runs the discovery program I(facter) on the remote system description: - - Runs the discovery program I(facter) on the remote system, returning JSON - data that can be useful for inventory purposes. + - Runs the I(facter) discovery program + (U(https://github.com/puppetlabs/facter)) on the remote system, returning + JSON data that can be useful for inventory purposes. version_added: "0.2" options: [] examples: diff --git a/library/file b/library/file index bf1eebf68b2..cc76327ff1e 100755 --- a/library/file +++ b/library/file @@ -46,19 +46,82 @@ options: aliases: [] state: description: - - If directory, all immediate subdirectories will be created if they do not exist. If I(file), the file will NOT be created if it does not exist, see the M(copy) or M(template) module if you want that behavior. If I(link), the symbolic link will be created or changed. If absent, directories will be recursively deleted, and files or symlinks will be unlinked. + - If C(directory), all immediate subdirectories will be created if they + do not exist. If C(file), the file will NOT be created if it does not + exist, see the M(copy) or M(template) module if you want that behavior. + If C(link), the symbolic link will be created or changed. If C(absent), + directories will be recursively deleted, and files or symlinks will be + unlinked. required: false default: file choices: [ file, link, directory, absent ] mode: + required: false + default: null + choices: [] description: - - mode the file or directory should be, such as 0644 as would be fed to I(chmod). English modes like B(g+x) are not yet supported + - mode the file or directory should be, such as 0644 as would be fed to + owner: + required: false + default: null + choices: [] + description: + - name of the user that should own the file/directory, as would be fed to I(chown) + group: + required: false + default: null + choices: [] + description: + - name of the group that should own the file/directory, as would be fed to I(chown) + src: + required: false + default: null + choices: [] + description: + - path of the file to link to (applies only to C(state=link)). + seuser: + required: false + default: null + choices: [] + description: + - user part of SELinux file context. Will default to system policy, if + applicable. If set to C(_default), it will use the C(user) portion of the + the policy if available + serole: + required: false + default: null + choices: [] + description: + - role part of SELinux file context, C(_default) feature works as for I(seuser). + setype: + required: false + default: null + choices: [] + description: + - type part of SELinux file context, C(_default) feature works as for I(seuser). + selevel: + required: false + default: "s0" + choices: [] + description: + - level part of the SELinux file context. This is the MLS/MCS attribute, + sometimes known as the C(range). C(_default) feature works as for + I(seuser). + context: + required: false + default: null + choices: [ "default" ] + description: + - accepts only C(default) as value. This will restore a file's SELinux context + in the policy. Does nothing if no default value is available. examples: - code: file path=/etc/foo.conf owner=foo group=foo mode=0644 description: Example from Ansible Playbooks + - code: file src=/file/to/link/to dest=/path/to/symlink owner=foo group=foo state=link notes: - See also M(copy), M(template), M(assemble) requirements: [ ] +author: Michael DeHaan ''' def add_path_info(kwargs): diff --git a/library/lineinfile b/library/lineinfile index 0166f6151c4..842ef947343 100755 --- a/library/lineinfile +++ b/library/lineinfile @@ -38,8 +38,8 @@ options: regexp: required: true description: - - The regular expression to look for in the file. For I(state=present), - the pattern to replace. For I(state=absent), the pattern of the line + - The regular expression to look for in the file. For C(state=present), + the pattern to replace. For C(state=absent), the pattern of the line to remove. state: required: false @@ -51,13 +51,13 @@ options: line: required: false description: - - Required for I(state=present). The line to insert/replace into the + - Required for C(state=present). The line to insert/replace into the file. Must match the value given to C(regexp). insertafter: required: false default: EOF description: - - Used with I(state=present). If specified, the line will be inserted + - Used with C(state=present). If specified, the line will be inserted after the specified regular expression. Two special values are available; C(BOF) for inserting the line at the beginning of the file, and C(EOF) for inserting the line at the end of the file. diff --git a/library/mysql_db b/library/mysql_db index 6082d17416e..85541a9da7c 100755 --- a/library/mysql_db +++ b/library/mysql_db @@ -65,10 +65,14 @@ options: default: null examples: - code: mysql_db db=bobdata state=present - description: create a new database with name 'bobdata' + description: Create a new database with name 'bobdata' notes: - - Requires the MySQLdb Python package on the remote host. For Ubuntu, this is as easy as apt-get install python-mysqldb. - - Both 'login_password' and 'login_username' are required when you are passing credentials. If none are present, the module will attempt to read the credentials from ~/.my.cnf, and finally fall back to using the MySQL default login of 'root' with no password. + - Requires the MySQLdb Python package on the remote host. For Ubuntu, this + is as easy as apt-get install python-mysqldb. + - Both C(login_password) and C(login_username) are required when you are + passing credentials. If none are present, the module will attempt to read + the credentials from C(~/.my.cnf), and finally fall back to using the MySQL + default login of 'root' with no password. requirements: [ ConfigParser ] author: Mark Theunissen ''' diff --git a/library/mysql_user b/library/mysql_user index be9cd00b3ac..c297c2a1aa9 100755 --- a/library/mysql_user +++ b/library/mysql_user @@ -75,9 +75,13 @@ examples: - code: mydb.*:INSERT,UPDATE/anotherdb.*:SELECT/yetanotherdb.*:ALL description: Example privileges string format notes: - - Requires the MySQLdb Python package on the remote host. For Ubuntu, this is as easy as apt-get install python-mysqldb. - - Both 'login_password' and 'login_username' are required when you are passing credentials. If none are present, the module will attempt to read the credentials from ~/.my.cnf, and finally fall back to using the MySQL default login of 'root' with no password. -requirements: [ ConfigParser ] + - Requires the MySQLdb Python package on the remote host. For Ubuntu, this + is as easy as apt-get install python-mysqldb. + - Both C(login_password) and C(login_username) are required when you are + passing credentials. If none are present, the module will attempt to read + the credentials from C(~/.my.cnf), and finally fall back to using the MySQL + default login of 'root' with no password. +requirements: [ "ConfigParser", "MySQLdb" ] author: Mark Theunissen ''' diff --git a/library/ohai b/library/ohai index 5a8281a80c2..b283c08bc27 100755 --- a/library/ohai +++ b/library/ohai @@ -24,7 +24,9 @@ DOCUMENTATION = ''' module: ohai short_description: Returns inventory data from I(ohai) description: - - Similar to the M(facter) module, this returns JSON inventory data. + - Similar to the M(facter) module, this runs the I(ohai) discovery program + (U(http://wiki.opscode.com/display/chef/Ohai)) on the remote host and + returns JSON inventory data. I(Ohai) data is a bit more verbose and nested than I(facter). version_added: "0.6" options: [] diff --git a/library/ping b/library/ping index dc183274662..95989f89bef 100755 --- a/library/ping +++ b/library/ping @@ -24,8 +24,10 @@ DOCUMENTATION = ''' module: ping short_description: Try to connect to host and return pong on success. description: - - A trivial test module, this module always returns 'pong' on successful contact. It does not make sense in playbooks, but is useful from /usr/bin/ansible -version_added: "0.7" + - A trivial test module, this module always returns 'pong' on successful + contact. It does not make sense in playbooks, but is useful from + C(/usr/bin/ansible) +version_added: "0.1" examples: - code: ansible webservers -m ping description: Test 'webservers' status diff --git a/library/pip b/library/pip index 27cd98a40bd..ec3a4731210 100755 --- a/library/pip +++ b/library/pip @@ -59,14 +59,14 @@ examples: - code: pip name=flask version=0.8 description: Install I(flask) python package on version 0.8. - code: pip name=flask virtualenv=/srv/webapps/my_app/venv - description: Install I(flask) python package in specified virtualenv. + description: "Install I(Flask) (U(http://flask.pocoo.org/)) into the specified I(virtualenv)" - code: pip requirements=/srv/webapps/my_app/src/requirements.txt description: Install specified python requirements. - code: pip requirements=/srv/webapps/my_app/src/requirements.txt virtualenv=/srv/webapps/my_app/venv description: Install specified python requirements in indicated virtualenv. notes: - Please note that U(http://www.virtualenv.org/, virtualenv) must be installed on the remote host if the virtualenv parameter is specified. -requirements: [ ] +requirements: [ "virtualenv", "pip" ] author: Matt Wright ''' diff --git a/library/postgresql_db b/library/postgresql_db index 65c0d0685d0..1caa24ec4b5 100755 --- a/library/postgresql_db +++ b/library/postgresql_db @@ -36,7 +36,7 @@ options: default: null login_password: description: - - The passwordused to authenticate with + - The password used to authenticate with required: false default: null login_host: @@ -57,7 +57,7 @@ options: choices: [ "present", "absent" ] examples: - code: postgresql_db db=acme - description: create a new database with name 'acme' + description: Create a new database with name 'acme' notes: - The default authentication assumes that you are either logging in as or sudo'ing to the postgres account on the host. - This module uses psycopg2, a Python PostgreSQL database adapter. You must ensure that psycopg2 is installed on the host before using this module. If the remote host is the PostgreSQL server (which is the default case), then PostgreSQL must also be installed on the remote host. For Ubuntu-based systems, install the postgresql, libpq-dev, and python-psycopg2 packages on the remote host before using this module. diff --git a/library/service b/library/service index 5616c34fd04..60d3939fb53 100755 --- a/library/service +++ b/library/service @@ -22,34 +22,36 @@ DOCUMENTATION = ''' --- module: service author: Michael DeHaan -version_added: 0.0.1 +version_added: 0.1 short_description: Manage services. description: - Controls services on remote hosts. options: name: required: true - description: Name of the service. + 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. + 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. + version_added: "0.7" + description: + - 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). + choices: [ "yes", "no" ] + description: + - Whether the service should start on boot. examples: - code: service name=httpd state=started description: Example action from Ansible Playbooks diff --git a/library/shell b/library/shell index 6f21c3ab7a0..02dec097dc2 100755 --- a/library/shell +++ b/library/shell @@ -7,8 +7,10 @@ DOCUMENTATION = ''' module: shell short_description: Execute commands in nodes. description: - - The shell module takes the command name followed by a list of arguments, space delimited. It is almost exactly like the command module but runs the command through the user's configured shell on the remote node. -version_added: "0.0.2" + - The shell module takes the command name followed by a list of arguments, + space delimited. It is almost exactly like the M(command) module but runs + the command through the user's configured shell on the remote node. +version_added: "0.2" options: (free form): description: @@ -29,7 +31,11 @@ examples: - code: shell somescript.sh >> somelog.txt description: Execute the command in remote shell notes: - - If you want to execute a command securely and predicably, it may be better to use the 'command' module instead. Best practices when writing playbooks will follow the trend of using M(command) unless M(shell) is explicitly required. When running ad-hoc commands, use your best judgement. + - If you want to execute a command securely and predicably, it may be + better to use the M(command) module instead. Best practices when writing + playbooks will follow the trend of using M(command) unless M(shell) is + explicitly required. When running ad-hoc commands, use your best + judgement. requirements: [ ] author: Michael DeHaan -''' \ No newline at end of file +''' diff --git a/library/template b/library/template index 42039f0eca0..610a45138fc 100755 --- a/library/template +++ b/library/template @@ -36,7 +36,8 @@ options: examples: - code: template src=/mytemplates/foo.j2 dest=/etc/file.conf owner=bin group=wheel mode=0644 description: "Example from Ansible Playbooks" -notes: [] +notes: + - Since Ansible version 0.9, templates are loaded with C(trim_blocks=True). requirements: null author: Michael DeHaan ''' diff --git a/library/user b/library/user index bc238ebb23f..f168d964528 100755 --- a/library/user +++ b/library/user @@ -22,7 +22,7 @@ DOCUMENTATION = ''' --- module: user author: Stephen Fromm -version_added: 0.0.2 +version_added: 0.2 short_description: Manage user accounts requirements: [ useradd, userdel, usermod ] description: