From caf003c81329a9559a831ee0d5236feb9ab32cd6 Mon Sep 17 00:00:00 2001 From: Jan-Piet Mens Date: Wed, 21 Nov 2012 18:49:30 +0100 Subject: [PATCH] DOCUMENTATION strings --- docsite/_static/bootstrap.css | 6 ++++-- docsite/_themes/bootstrap/static/bootstrap.css | 6 ++++-- docsite/rst/moduledev.rst | 7 +++++++ hacking/module_formatter.py | 8 ++------ library/apt | 8 ++++---- library/apt_repository | 4 ++-- library/assemble | 2 +- library/command | 4 ++-- library/cron | 4 ++-- library/debug | 4 ++-- library/ec2 | 12 ++++++------ library/fail | 4 ++-- library/fetch | 4 ++-- library/file | 8 ++++---- library/fireball | 14 +++++++------- library/get_url | 6 +++--- library/git | 9 +++++---- library/lineinfile | 2 +- library/mysql_db | 8 ++++---- library/nagios | 8 ++++---- library/ohai | 4 ++-- library/ping | 6 +++--- library/pip | 6 +++--- library/postgresql_db | 7 ++++--- library/postgresql_user | 4 ++-- library/raw | 4 ++-- library/script | 2 +- library/seboolean | 2 +- library/selinux | 2 +- library/service | 7 +++---- library/setup | 4 ++-- library/shell | 5 +++-- library/slurp | 2 +- library/subversion | 4 ++-- library/supervisorctl | 4 ++-- library/svr4pkg | 4 ++-- library/user | 16 ++++++++-------- library/yum | 2 +- 38 files changed, 111 insertions(+), 102 deletions(-) diff --git a/docsite/_static/bootstrap.css b/docsite/_static/bootstrap.css index e5aa166089b..3ab0f1ff55b 100644 --- a/docsite/_static/bootstrap.css +++ b/docsite/_static/bootstrap.css @@ -543,10 +543,12 @@ code, pre { -moz-border-radius: 3px; border-radius: 3px; } +.module { + font-family: Monaco, Andale Mono, Courier New, monospace; + font-size: 12px; +} code { - background-color: #fee9cc; color: rgba(0, 0, 0, 0.75); - padding: 1px 3px; } pre { background-color: #f5f5f5; diff --git a/docsite/_themes/bootstrap/static/bootstrap.css b/docsite/_themes/bootstrap/static/bootstrap.css index e5aa166089b..3ab0f1ff55b 100644 --- a/docsite/_themes/bootstrap/static/bootstrap.css +++ b/docsite/_themes/bootstrap/static/bootstrap.css @@ -543,10 +543,12 @@ code, pre { -moz-border-radius: 3px; border-radius: 3px; } +.module { + font-family: Monaco, Andale Mono, Courier New, monospace; + font-size: 12px; +} code { - background-color: #fee9cc; color: rgba(0, 0, 0, 0.75); - padding: 1px 3px; } pre { background-color: #f5f5f5; diff --git a/docsite/rst/moduledev.rst b/docsite/rst/moduledev.rst index d63dd7b6f6b..6436aa9e1f8 100644 --- a/docsite/rst/moduledev.rst +++ b/docsite/rst/moduledev.rst @@ -347,6 +347,13 @@ Include it in your module file like this:: description: Optional words describing this example ''' +The ``description``, ``notes`` and ``description`` within ``examples`` +support formatting in some of the output formats (e.g. ``rst``, ``man``). +These formatting functions are ``U()``, ``M()``, ``I()``, and ``C()`` +for URL, module, italic, and constant-width respectively. It is suggested +to use ``C()`` for file and option names, and ``I()`` when referencing +parameters; module names should be specifies as ``M(module)``. + Building & Testing ++++++++++++++++++ diff --git a/hacking/module_formatter.py b/hacking/module_formatter.py index 792bdad5f1b..e4f8dab45d6 100755 --- a/hacking/module_formatter.py +++ b/hacking/module_formatter.py @@ -100,13 +100,9 @@ def rst_ify(text): t = _ITALIC.sub(r'*' + r"\1" + r"*", text) t = _BOLD.sub(r'**' + r"\1" + r"**", t) - # mdehaan is disabling because he finds all the Sphinx orange distracting - #t = _MODULE.sub(r'``' + r"\1" + r"``", t) - t = _MODULE.sub(r"\1", t) + t = _MODULE.sub(r'``' + r"\1" + r"``", t) t = _URL.sub(r"\1", t) - # ditto - # t = _CONST.sub(r'``' + r"\1" + r"``", t) - t = _CONST.sub(r"\1", t) + t = _CONST.sub(r'``' + r"\1" + r"``", t) return t diff --git a/library/apt b/library/apt index 4e4fa1dea0d..b15580070bd 100644 --- a/library/apt +++ b/library/apt @@ -24,7 +24,7 @@ DOCUMENTATION = ''' module: apt short_description: Manages apt-packages description: - - Manages apt-packages (such as for Debian/Ubuntu). + - Manages I(apt) packages (such as for Debian/Ubuntu). version_added: "0.0.2" options: pkg: @@ -40,13 +40,13 @@ options: choices: [ "latest", "absent", "present" ] update_cache: description: - - Run the equivalent of C(apt-get update) before the operation. Can be run as part of the package installation or as a seperate step + - Run the equivalent of C(apt-get update) before the operation. Can be run as part of the package installation or as a separate step required: false default: "no" choices: [ "yes", "no" ] purge: description: - - Will force purging of configuration files if the module state is set to C(absent). + - Will force purging of configuration files if the module state is set to I(absent). required: false default: "no" choices: [ "yes", "no" ] @@ -81,7 +81,7 @@ examples: - code: "apt: pkg=nginx state=latest default-release=squeeze-backports update-cache=yes" description: Update the repository cache and update package C(ngnix) to latest version using default release C(squeeze-backport) - code: "apt: pkg=openjdk-6-jdk state=latest install-recommends=no" - description: Install latest version of C(openjdk-6-jdk) ignoring C(install-recomands) + description: Install latest version of C(openjdk-6-jdk) ignoring C(install-reccomends) ''' import traceback diff --git a/library/apt_repository b/library/apt_repository index 2f2fdf867cd..eef848381e8 100644 --- a/library/apt_repository +++ b/library/apt_repository @@ -28,7 +28,7 @@ DOCUMENTATION = ''' module: apt_repository short_description: Manages apt repositores description: - - Manages apt repositores (such as for Debian/Ubuntu). + - Manages apt repositories (such as for Debian/Ubuntu). version_added: "0.7" options: repo: @@ -43,7 +43,7 @@ options: default: present choices: [ "present", "absent" ] notes: - - This module works on Debian and Ubuntu only and 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 Debian and Ubuntu only and requires C(apt-add-repository) be available on the destination server. To ensure this package is available use the M(apt) module and install the C(python-software-properties) package before using this module. - This module cannot be used on Debian Squeeze (Version 6) as there is no C(add-apt-repository) in C(python-software-properties) - 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 a repo doesn't have source information (eg MongoDB repo from 10gen) the system will fail while updating repositories. author: Matt Wright diff --git a/library/assemble b/library/assemble index 88dca33deaa..70f429c564f 100644 --- a/library/assemble +++ b/library/assemble @@ -31,7 +31,7 @@ description: - Assembles a configuration file from fragments. Often a particular program will take a single configuration file and does not support a C(conf.d) style structure where it is easy to build up the configuration - from multiple sources. Assemble will take a directory of files that have + from multiple sources. M(assemble) will take a directory of files that have already been transferred to the system, and concatenate them together to produce a destination file. Files are assembled in string sorting order. Puppet calls this idea I(fragments). diff --git a/library/command b/library/command index 322df8ce31a..58e63cc613f 100644 --- 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 space-delimited arguments. + - The M(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 @@ -70,7 +70,7 @@ examples: - code: "command: /sbin/shutdown -t now" description: "Example from Ansible Playbooks" - code: "command: /usr/bin/make_database.sh arg1 arg2 creates=/path/to/database" - description: "I(creates), I(removes), and I(chdir) can be specified after the command. For instance, if you only want to run a command if a certain file does not exist, use this." + description: "C(creates), C(removes), and C(chdir) can be specified after the command. For instance, if you only want to run a command if a certain file does not exist, use this." notes: - If you want to run a command through the shell (say you are using C(<), C(>), C(|), etc), you actually want the M(shell) module instead. The diff --git a/library/cron b/library/cron index c04cd27337f..177c427080b 100644 --- a/library/cron +++ b/library/cron @@ -31,7 +31,7 @@ short_description: Manage crontab entries. description: - Use this module to manage crontab entries. This module allows you to create named crontab entries, update, or delete them. - - 'The module include one line with the description of the crontab entry "#Ansible: " + - 'The module includes one line with the description of the crontab entry C("#Ansible: ") corresponding to the "name" passed to the module, which is used by future ansible/module calls to find/check the state.' version_added: "0.9" @@ -64,7 +64,7 @@ options: backup: description: - If set, then create a backup of the crontab before it is modified. - - The location of the backup is returned in the 'backup' variable by this module. + - The location of the backup is returned in the C(backup) variable by this module. required: false default: false aliases: [] diff --git a/library/debug b/library/debug index acd7efd2c53..3ec1e809a00 100644 --- a/library/debug +++ b/library/debug @@ -28,12 +28,12 @@ description: the playbook. Useful for debugging together with the only_if directive. In order to see the debug message, you need to run ansible in verbose - mode (using the -v option). + mode (using the C(-v) option). version_added: "0.8" options: msg: description: - - The customized message that is printed. If ommited, prints a generic + - The customized message that is printed. If omitted, prints a generic message. required: false default: "Hello world!" diff --git a/library/ec2 b/library/ec2 index 306af081dac..d8c42919bd4 100644 --- a/library/ec2 +++ b/library/ec2 @@ -19,12 +19,12 @@ DOCUMENTATION = ''' module: ec2 short_description: create an instance in ec2, return instanceid description: - - creates ec2 instances and optionally waits for it to be 'running'. This module has a dependency on the external euca2ools package. + - creates ec2 instances and optionally waits for it to be 'running'. This module has a dependency on the external I(euca2ools) package. version_added: "0.9" options: keypair: description: - - keypair to use on the instance + - key pair to use on the instance required: true default: null aliases: [] @@ -42,19 +42,19 @@ options: aliases: [] image: description: - - emi (or ami) to use for the instance + - I(emi) (or I(ami)) to use for the instance required: true default: null aliases: [] kernel: description: - - kernel eki to use for the instance + - kernel I(eki) to use for the instance required: false default: null aliases: [] ramdisk: description: - - ramdisk eri to use for the instance + - ramdisk I(eri) to use for the instance required: false default: null aliases: [] @@ -66,7 +66,7 @@ options: aliases: [] ec2_url: description: - - url to use to connect to ec2 or your cloud (for example https://ec2.amazonaws.com when using Amazon ec2 directly and not Eucalyptus) + - url to use to connect to ec2 or your cloud (for example U(https://ec2.amazonaws.com) when using Amazon ec2 directly and not Eucalyptus) required: False default: null aliases: [] diff --git a/library/fail b/library/fail index c6fbe603a54..2f9aa37438e 100644 --- a/library/fail +++ b/library/fail @@ -24,12 +24,12 @@ module: fail short_description: Fail with custom message description: - This module fails the progress with a custom message. It can be - useful for bailing out when a certain condition is met using only_if. + useful for bailing out when a certain condition is met using C(only_if). version_added: "0.8" options: msg: description: - - The customized message used for failing execution. If ommited, + - The customized message used for failing execution. If omitted, fail will simple bail out with a generic message. required: false default: "'Failed as requested from task'" diff --git a/library/fetch b/library/fetch index b37170f7892..5b8d311cb79 100644 --- a/library/fetch +++ b/library/fetch @@ -12,7 +12,7 @@ version_added: "0.2" options: src: description: - - The file on the remote system to fetch. This must be a file, not a + - The file on the remote system to fetch. This I(must) be a file, not a directory. Recursive fetching may be supported in a later release. required: true default: null @@ -20,7 +20,7 @@ options: dest: description: - A directory to save the file into. For example, if the I(dest) - directory is C(/backup) a src file named C(/etc/profile) on host + directory is C(/backup) a I(src) file named C(/etc/profile) on host C(host.example.com), would be saved into C(/backup/host.example.com/etc/profile) required: true diff --git a/library/file b/library/file index 99325477658..a4c05423414 100644 --- a/library/file +++ b/library/file @@ -35,11 +35,11 @@ short_description: Sets attributes of files description: - Sets attributes of files, symlinks, and directories, or removes files/symlinks/directories. Many other modules support the same options as - the file module - including M(copy), M(template), and M(assmeble). + the file module - including M(copy), M(template), and M(assemble). options: path: description: - - defines the file being managed, unless when used with I(state=link), and then sets the destination to create a symbolic link to using I(src) + - defines the file being managed, unless when used with C(state=link), and then sets the destination to create a symbolic link to using I(src) required: true default: [] aliases: [] @@ -59,7 +59,7 @@ options: default: null choices: [] description: - - mode the file or directory should be, such as 0644 as would be fed to + - mode the file or directory should be, such as 0644 as would be fed to I(chmod) owner: required: false default: null @@ -85,7 +85,7 @@ options: 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 + policy if available serole: required: false default: null diff --git a/library/fireball b/library/fireball index d8cbc4c150a..16f3f580514 100644 --- a/library/fireball +++ b/library/fireball @@ -24,7 +24,7 @@ module: fireball short_description: Enable fireball mode on remote node description: - This modules launches an ephemeral I(fireball) ZeroMQ message bus daemon on the remote node which - Ansible can to communicate with nodes at high speed. + Ansible can use to communicate with nodes at high speed. - The daemon listens on a configurable port for a configurable amount of time. - Starting a new fireball as a given user terminates any existing user fireballs. - Fireball mode is AES encrypted @@ -50,7 +50,7 @@ examples: connection: ssh sudo: yes tasks: - - action: fireball + - action: fireball - hosts: devservers connection: fireball tasks: @@ -160,7 +160,7 @@ def command(data): log("got stdout: %s" % stdout) return dict(stdout=stdout, stderr=stderr) - + def fetch(data): if 'in_path' not in data: return dict(failed=True, msg='internal error: in_path is required') @@ -179,7 +179,7 @@ def put(data): return dict(failed=True, msg='internal error: data is required') if 'out_path' not in data: return dict(failed=True, msg='internal error: out_path is required') - + # FIXME: should probably support chunked file transfer for binary files # at some point. For now, just base64 encodes the file # so don't use it to move ISOs, use rsync. @@ -204,7 +204,7 @@ def serve(module, password, port, minutes): # password as a variable in ansible is never logged though, so it serves well key = AesKey.Read(password) - + while True: data = socket.recv() @@ -264,10 +264,10 @@ def main(): if not HAS_ZMQ: module.fail_json(msg="zmq is not installed") if not HAS_KEYCZAR: - module.fail_json(msg="keyczar is not installed") + module.fail_json(msg="keyczar is not installed") daemonize(module, password, port, minutes) - + # this is magic, see lib/ansible/module_common.py #<> diff --git a/library/get_url b/library/get_url index cb6a927e811..933c4445b2b 100644 --- a/library/get_url +++ b/library/get_url @@ -30,7 +30,7 @@ module: get_url short_description: Downloads files from HTTP, HTTPS, or FTP to node description: - Downloads files from HTTP, HTTPS, or FTP to the remote server. The remote - server must have direct access to the remote resource. + server I(must) have direct access to the remote resource. version_added: "0.6" options: url: @@ -42,13 +42,13 @@ options: dest: description: - absolute path of where to download the file to. - - If I(dest) is a directory, the basename of the file on the remote server will be used. If a directory, I(thirsty=yes) must also be set. + - If I(dest) is a directory, the basename of the file on the remote server will be used. If a directory, C(thirsty=yes) must also be set. required: true default: null thirsty: description: - if C(yes), will download the file every time and replace the - file if the contents change. if C(no), the file will only be downloaded if + file if the contents change. If C(no), the file will only be downloaded if the destination does not exist. Generally should be C(yes) only for small local files. prior to 0.6, acts if C(yes) by default. version_added: "0.7" diff --git a/library/git b/library/git index f5cf10b0f6e..dd4a968f9fe 100644 --- a/library/git +++ b/library/git @@ -25,13 +25,13 @@ 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. + - Manage I(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. + - git, SSH, or HTTP protocol address of the git repository. dest: required: true description: @@ -41,7 +41,7 @@ options: 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. + git I(SHA), the literal string C(HEAD), a branch name, or a tag name. remote: required: false default: "origin" @@ -51,8 +51,9 @@ options: required: false default: "yes" choices: [ yes, no ] + version_added: "0.7" description: - - (New in 0.7) If yes, any modified files in the working + - If C(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: diff --git a/library/lineinfile b/library/lineinfile index abec9cc3cfa..d9d1422b907 100644 --- a/library/lineinfile +++ b/library/lineinfile @@ -54,7 +54,7 @@ options: required: false description: - Required for C(state=present). The line to insert/replace into the - file. Must match the value given to C(regexp). + file. Must match the value given to I(regexp). insertafter: required: false default: EOF diff --git a/library/mysql_db b/library/mysql_db index c1e25e31b2a..468a9b8d210 100644 --- a/library/mysql_db +++ b/library/mysql_db @@ -65,18 +65,18 @@ options: default: null target: description: - - Where to dump/get the .sql file + - Where to dump/get the C(.sql) file required: true examples: - code: "mysql_db: db=bobdata state=present" 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 C(login_password) and C(login_username) are required when you are + is as easy as apt-get install python-mysqldb. (See M(apt).) + - Both I(login_password) and I(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. + default login of C(root) with no password. requirements: [ ConfigParser ] author: Mark Theunissen ''' diff --git a/library/nagios b/library/nagios index d46ed223ca0..369b6a8f15f 100644 --- a/library/nagios +++ b/library/nagios @@ -21,10 +21,10 @@ module: nagios short_description: Perform common tasks in Nagios related to downtime and notifications. description: - "The M(nagios) module has two basic functions: scheduling downtime and toggling alerts for services or hosts." - - All actions require the C(host) parameter to be given explicitly. In playbooks you can use the C($inventory_hostname) variable to refer to the host the playbook is currently running on. + - All actions require the I(host) parameter to be given explicitly. In playbooks you can use the C($inventory_hostname) variable to refer to the host the playbook is currently running on. - You can specify multiple services at once by separating them with commas, .e.g., C(services=httpd,nfs,puppet). - When specifying what service to handle there is a special service value, I(host), which will handle alerts/downtime for the I(host itself), e.g., C(service=host). This keyword may not be given with other services at the same time. I(Setting alerts/downtime for a host does not affect alerts/downtime for any of the services running on it.) - - When using the M(nagios) module you will need to specify your nagios server using the C(delegate_to) parameter. + - When using the M(nagios) module you will need to specify your Nagios server using the C(delegate_to) parameter. version_added: 0.7 options: action: @@ -47,13 +47,13 @@ options: author: description: - Author to leave downtime comments as. - - Only useable with the C(downtime) action. + - Only usable with the C(downtime) action. required: false default: Ansible minutes: description: - Minutes to schedule downtime for. - - Only useable with the C(downtime) action. + - Only usable with the C(downtime) action. required: false default: 30 services: diff --git a/library/ohai b/library/ohai index 95d764f075e..791a2cb5402 100644 --- a/library/ohai +++ b/library/ohai @@ -22,9 +22,9 @@ DOCUMENTATION = ''' --- module: ohai -short_description: Returns inventory data from I(ohai) +short_description: Returns inventory data from I(Ohai) description: - - Similar to the M(facter) module, this runs the I(ohai) discovery program + - 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). diff --git a/library/ping b/library/ping index 36f8bcbbaef..ba697920cf9 100644 --- a/library/ping +++ b/library/ping @@ -22,10 +22,10 @@ DOCUMENTATION = ''' --- module: ping -short_description: Try to connect to host and return pong on success. +short_description: Try to connect to host and return C(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 + - A trivial test module, this module always returns C(pong) on successful + contact. It does not make sense in playbooks, but it is useful from C(/usr/bin/ansible) options: {} examples: diff --git a/library/pip b/library/pip index d07b2a8ab1b..7ca62ca107c 100644 --- a/library/pip +++ b/library/pip @@ -34,7 +34,7 @@ options: default: null version: description: - - The version number to install of the Python library specified in the 'name' parameter + - The version number to install of the Python library specified in the I(name) parameter required: false default: null requirements: @@ -44,7 +44,7 @@ options: default: null virtualenv: description: - - An optional path to a virtualenv directory to install into + - An optional path to a I(virtualenv) directory to install into required: false default: null state: @@ -63,7 +63,7 @@ examples: - 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. + description: Install specified python requirements in indicated I(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: [ "virtualenv", "pip" ] diff --git a/library/postgresql_db b/library/postgresql_db index 1759f5ee2b7..af1b472f257 100644 --- a/library/postgresql_db +++ b/library/postgresql_db @@ -57,10 +57,11 @@ 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 C(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. + - The default authentication assumes that you are either logging in as or sudo'ing to the C(postgres) account on the host. + - This module uses I(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 C(postgresql), C(libpq-dev), and C(python-psycopg2) packages on the remote host before using this module. requirements: [ psycopg2 ] author: Lorin Hochstein ''' diff --git a/library/postgresql_user b/library/postgresql_user index b38949c43cc..39dd9d5183d 100644 --- a/library/postgresql_user +++ b/library/postgresql_user @@ -28,7 +28,7 @@ description: step, which works on one database at a time. This allows for the module to be called several times in the same module to modify the permissions on different databases, or to grant permissions to already existing users. - - A user cannot be removed untill all the privileges have been stripped from + - A user cannot be removed until all the privileges have been stripped from the user. In such situation, if the module tries to remove the user it will fail. To avoid this from happening the fail_on_user option signals the module to try to remove the user, but if not possible keep going; the @@ -53,7 +53,7 @@ options: default: null fail_on_user: description: - - if yes, fail when user can't be removed. Otherwise just log and continue + - if C(yes), fail when user can't be removed. Otherwise just log and continue required: false default: yes choices: [ "yes", "no" ] diff --git a/library/raw b/library/raw index 39add7372f5..1b46f2f886f 100644 --- a/library/raw +++ b/library/raw @@ -8,7 +8,7 @@ options: {} description: - Executes a low-down and dirty SSH command, not going through the module subsystem. This is useful and should only be done in two cases. The - first case is installing python-simplejson on older (Python 2.4 and + first case is installing C(python-simplejson) on older (Python 2.4 and before) hosts that need it as a dependency to run modules, since nearly all core modules require it. Another is speaking to any devices such as routers that do not have any Python installed. In any other case, using @@ -18,6 +18,6 @@ description: support for this module examples: - code: ansible newhost.example.com -m raw -a "yum -y install python-simplejson" - description: Example from /usr/bin/ansible to bootstrap a legacy python 2.4 host + description: Example from C(/usr/bin/ansible) to bootstrap a legacy python 2.4 host author: Michael DeHaan ''' diff --git a/library/script b/library/script index 3a1614e8087..4f26ec22258 100644 --- a/library/script +++ b/library/script @@ -17,7 +17,7 @@ examples: - description: "Example from Ansible Playbooks" code: "script: /some/local/script.sh --some-arguments 1234" notes: - - It is preferable to write Ansible modules than pushing scripts. Convert your script to an ansible module for bonus points! + - It is preferable to write Ansible modules than pushing scripts. Convert your script to an Ansible module for bonus points! author: Michael DeHaan """ diff --git a/library/seboolean b/library/seboolean index d9a3222ca0e..aee16693982 100644 --- a/library/seboolean +++ b/library/seboolean @@ -32,7 +32,7 @@ options: default: null persistent: description: - - Set to 'yes' if the boolean setting should survive a reboot + - Set to C(yes) if the boolean setting should survive a reboot required: false default: no choices: [ "yes", "no" ] diff --git a/library/selinux b/library/selinux index c8b624e6785..c2965a33398 100644 --- a/library/selinux +++ b/library/selinux @@ -28,7 +28,7 @@ version_added: "0.7" options: policy: description: - - "name of the SELinux policy to use (example: 'targeted') will be required if state is not 'disabled'" + - "name of the SELinux policy to use (example: C(targeted)) will be required if state is not C(disabled)" required: false default: null state: diff --git a/library/service b/library/service index 911494d939f..fcb536374c5 100644 --- a/library/service +++ b/library/service @@ -35,10 +35,9 @@ options: required: false choices: [ 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. + C(Started)/C(stopped) are idempotent actions that will not run + commands unless necessary. C(restarted) will always bounce the + service. C(reloaded) will always reload. pattern: required: false version_added: "0.7" diff --git a/library/setup b/library/setup index 480964e9c61..6be75050f14 100644 --- a/library/setup +++ b/library/setup @@ -44,10 +44,10 @@ notes: with C(facter_) and C(ohai_) so it's easy to tell their source. All variables are bubbled up to the caller. Using the ansible facts and choosing to not install I(facter) and I(ohai) means you can avoid Ruby-dependencies on your - remote systems. + remote systems. (See also M(facter) and M(ohai).) examples: - code: ansible all -m setup --tree /tmp/facts - description: Obtain facts from all hosts and store them indexed by hostname at /tmp/facts. + description: Obtain facts from all hosts and store them indexed by I(hostname) at C(/tmp/facts). author: Michael DeHaan ''' diff --git a/library/shell b/library/shell index df7e47061ac..13c6041f022 100644 --- a/library/shell +++ b/library/shell @@ -24,9 +24,10 @@ options: default: null chdir: description: - - cd into this directory before running the command (0.6 and later) + - cd into this directory before running the command required: false default: null + version_added: "0.6" executable: description: - change the shell used to execute the command. Should be an absolute path to the executable. @@ -37,7 +38,7 @@ 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 + - If you want to execute a command securely and predictably, 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 diff --git a/library/slurp b/library/slurp index 4564ddb093e..ccc64950175 100644 --- a/library/slurp +++ b/library/slurp @@ -28,7 +28,7 @@ description: options: src: description: - - The file on the remote system to fetch. This must be a file, not a + - The file on the remote system to fetch. This I(must) be a file, not a directory. required: true default: null diff --git a/library/subversion b/library/subversion index d04954defa9..0233fee9a0b 100644 --- a/library/subversion +++ b/library/subversion @@ -38,7 +38,7 @@ options: default: null force: description: - - If yes, any modified files in the working repository will be discarded. If no, this module will fail if it encounters modified files. + - If C(yes), any modified files in the working repository will be discarded. If C(no), this module will fail if it encounters modified files. required: false default: yes choices: [ "yes", "no" ] @@ -46,7 +46,7 @@ examples: - code: "subversion: repo=svn+ssh://an.example.org/path/to/repo dest=/src/checkout" description: Export subversion repository in a specified folder notes: - - Requires subversion and grep on the client. + - Requires I(subversion) and I(grep) on the client. requirements: [ ] author: Dane Summers ''' diff --git a/library/supervisorctl b/library/supervisorctl index 1031d602a89..548c79e623b 100644 --- a/library/supervisorctl +++ b/library/supervisorctl @@ -24,12 +24,12 @@ DOCUMENTATION = ''' module: supervisorctl short_description: Manage the state of a program or group of programs running via Supervisord description: - - Manage the state of a program or group of programs running via Supervisord + - Manage the state of a program or group of programs running via I(Supervisord) version_added: "0.7" options: name: description: - - The name of the supervisord program/process to manage + - The name of the I(supervisord) program/process to manage required: true default: null state: diff --git a/library/svr4pkg b/library/svr4pkg index 5735a7bc160..8ce8fd628e4 100644 --- a/library/svr4pkg +++ b/library/svr4pkg @@ -40,7 +40,7 @@ options: state: description: - Whether to install (C(present)), or remove (C(absent)) a package. - - If the package is to be installed, then C(src) is required. + - If the package is to be installed, then I(src) is required. - The SVR4 package system doesn't provide an upgrade operation. You need to uninstall the old, then install the new package. required: true choices: ["present", "absent"] @@ -49,7 +49,7 @@ options: description: - Specifies the location to install the package from. Required when C(state=present). - "Can be any path acceptable to the C(pkgadd) command's C(-d) option. e.g.: C(somefile.pkg), C(/dir/with/pkgs), C(http:/server/mypkgs.pkg)." - - If using a file or directory, they must already be accessible by the host. See the I(copy) module for a way to get them there. + - If using a file or directory, they must already be accessible by the host. See the M(copy) module for a way to get them there. proxy: description: - HTTP[s] proxy to be used if C(src) is a URL. diff --git a/library/user b/library/user index 18e15cb42e0..1e7929d0f44 100644 --- a/library/user +++ b/library/user @@ -52,7 +52,7 @@ options: append: required: false description: - - If I(yes), will only add groups, not set them to just the list + - If C(yes), will only add groups, not set them to just the list in I(groups). shell: required: false @@ -73,36 +73,36 @@ options: default: "present" choices: [ present, absent ] description: - - Whether the account should exist. When I(absent), removes + - Whether the account should exist. When C(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 + - Unless set to C(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 + - When creating an account, setting this to C(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). + - When used with C(state=absent), behavior is as with + C(userdel --force). remove: required: false default: "no" choices: [ yes, no ] description: - - When used with I(state=absent), behavior is as with - I(userdel --remove). + - When used with C(state=absent), behavior is as with + C(userdel --remove). generate_ssh_key: required: false default: "no" diff --git a/library/yum b/library/yum index d51776e85a0..be226e3a270 100644 --- a/library/yum +++ b/library/yum @@ -61,7 +61,7 @@ options: disablerepo: description: - - Repoid of repositories to disable for the install/update operation + - I(repoid) of repositories to disable for the install/update operation These repos will not persist beyond the transaction Multiple repos separated with a ',' New in version 0.9.