diff --git a/docs/docsite/rst/dev_guide/developing_modules.rst b/docs/docsite/rst/dev_guide/developing_modules.rst index e7efdc1b28..eb88ab167e 100644 --- a/docs/docsite/rst/dev_guide/developing_modules.rst +++ b/docs/docsite/rst/dev_guide/developing_modules.rst @@ -13,14 +13,14 @@ This section discusses how to develop, debug, review, and test modules. Ansible modules are reusable, standalone scripts that can be used by the Ansible API, or by the :command:`ansible` or :command:`ansible-playbook` programs. They return information to ansible by printing a JSON string to stdout before -exiting. They take arguments in in one of several ways which we'll go into +exiting. They take arguments in one of several ways which we'll go into as we work through this tutorial. See :doc:`../modules` for a list of existing modules. Modules can be written in any language and are found in the path specified by :envvar:`ANSIBLE_LIBRARY` or the ``--module-path`` command line option or -in the `library section of the Ansible configration file `_. +in the `library section of the Ansible configuration file `_. .. _module_dev_should_you: diff --git a/docs/docsite/rst/dev_guide/developing_modules_best_practices.rst b/docs/docsite/rst/dev_guide/developing_modules_best_practices.rst index 9e7e546d65..19f56e2fda 100644 --- a/docs/docsite/rst/dev_guide/developing_modules_best_practices.rst +++ b/docs/docsite/rst/dev_guide/developing_modules_best_practices.rst @@ -18,7 +18,7 @@ and guidelines: * If packaging modules in an RPM, they only need to be installed on the control machine and should be dropped into /usr/share/ansible. This is entirely optional and up to you. -* Modules must output valid JSON only. The toplevel return type must be a hash (dictionary) although they can be nested. Lists or simple scalar values are not supported, though they can be trivially contained inside a dictionary. +* Modules must output valid JSON only. The top level return type must be a hash (dictionary) although they can be nested. Lists or simple scalar values are not supported, though they can be trivially contained inside a dictionary. * In the event of failure, a key of 'failed' should be included, along with a string explanation in 'msg'. Modules that raise tracebacks (stacktraces) are generally considered 'poor' modules, though Ansible can deal with these returns and will automatically convert anything unparseable into a failed result. If you are using the AnsibleModule common Python code, the 'failed' element will be included for you automatically when you call 'fail_json'. @@ -72,7 +72,7 @@ your debugging session will start: Setting :envvar:`ANSIBLE_KEEP_REMOTE_FILES` to ``1`` tells Ansible to keep the remote module files instead of deleting them after the module finishes -executing. Giving Ansible the ``-vvv`` optin makes Ansible more verbose. +executing. Giving Ansible the ``-vvv`` option makes Ansible more verbose. That way it prints the file name of the temporary module file for you to see. If you want to examine the wrapper file you can. It will show a small python @@ -103,13 +103,13 @@ When you look into the debug_dir you'll see a directory structure like this:: * The :file:`args` file contains a JSON string. The string is a dictionary containing the module arguments and other variables that Ansible passes into - the module to change it's behaviour. If you want to modify the parameters + the module to change its behaviour. If you want to modify the parameters that are passed to the module, this is the file to do it in. * The :file:`ansible` directory contains code from :mod:`ansible.module_utils` that is used by the module. Ansible includes files for any :`module:`ansible.module_utils` imports in the module but not - no files from any other module. So if your module uses + any files from any other module. So if your module uses :mod:`ansible.module_utils.url` Ansible will include it for you, but if your module includes :mod:`requests` then you'll have to make sure that the python requests library is installed on the system before running the @@ -183,7 +183,7 @@ how the command module is implemented. If a module returns stderr or otherwise fails to produce valid JSON, the actual output will still be shown in Ansible, but the command will not succeed. -Don't write to files directly; use a temporary file and then use the `atomic_move` function from `ansibile.module_utils.basic` to move the updated temporary file into place. This prevents data corruption and ensures that the correct context for the file is kept. +Don't write to files directly; use a temporary file and then use the `atomic_move` function from `ansible.module_utils.basic` to move the updated temporary file into place. This prevents data corruption and ensures that the correct context for the file is kept. Avoid creating a module that does the work of other modules; this leads to code duplication and divergence, and makes things less uniform, unpredictable and harder to maintain. Modules should be the building blocks. Instead of creating a module that does the work of other modules, use Plays and Roles instead. diff --git a/docs/docsite/rst/dev_guide/developing_modules_general.rst b/docs/docsite/rst/dev_guide/developing_modules_general.rst index 0a5a481754..f8e9c76a4c 100644 --- a/docs/docsite/rst/dev_guide/developing_modules_general.rst +++ b/docs/docsite/rst/dev_guide/developing_modules_general.rst @@ -3,7 +3,7 @@ Building A Simple Module ```````````````````````` -Let's build a very-basic module to get and set the system time. For starters, let's build +Let's build a very basic module to get and set the system time. For starters, let's build a module that just outputs the current time. We are going to use Python here but any language is possible. Only File I/O and outputting to standard @@ -71,7 +71,7 @@ If you did not, you might have a typo in your module, so recheck it and try agai Reading Input ````````````` Let's modify the module to allow setting the current time. We'll do this by seeing -if a key value pair in the form `time=` is passed in to the module. +if a key value pair in the form `time=` is passed into the module. Ansible internally saves arguments to an arguments file. So we must read the file and parse it. The arguments file is just a string, so any form of arguments are legal. diff --git a/docs/docsite/rst/faq.rst b/docs/docsite/rst/faq.rst index 19ee54da7f..c397a21a8c 100644 --- a/docs/docsite/rst/faq.rst +++ b/docs/docsite/rst/faq.rst @@ -1,7 +1,7 @@ Frequently Asked Questions ========================== -Here are some commonly-asked questions and their answers. +Here are some commonly asked questions and their answers. .. _set_environment: @@ -9,7 +9,7 @@ Here are some commonly-asked questions and their answers. How can I set the PATH or any other environment variable for a task or entire playbook? +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -Setting environment variables can be done with the `environment` keyword. It can be used at task or play level:: +Setting environment variables can be done with the `environment` keyword. It can be used at the task or the play level:: environment: PATH: "{{ ansible_env.PATH }}:/thingy/bin" @@ -111,10 +111,10 @@ How do I handle python pathing not having a Python 2.X in /usr/bin/python on a r While you can write ansible modules in any language, most ansible modules are written in Python, and some of these are important core ones. -By default Ansible assumes it can find a /usr/bin/python on your remote system that is a 2.X version of Python, specifically +By default, Ansible assumes it can find a /usr/bin/python on your remote system that is a 2.X version of Python, specifically 2.6 or higher. -Setting of an inventory variable 'ansible_python_interpreter' on any host will allow Ansible to auto-replace the interpreter +Setting the inventory variable 'ansible_python_interpreter' on any host will allow Ansible to auto-replace the interpreter used when executing python modules. Thus, you can point to any python you want on the system if /usr/bin/python on your system does not point to a Python 2.X interpreter. @@ -173,7 +173,7 @@ This will print out a dictionary of all of the facts that are available for that How do I see all the inventory vars defined for my host? ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -You can see the resulting vars you define in inventory running the following command: +By running the following command, you can see vars resulting from what you've defined in the inventory: .. code-block:: shell-session @@ -229,7 +229,7 @@ How do I access a variable of the first host in a group? What happens if we want the ip address of the first webserver in the webservers group? Well, we can do that too. Note that if we are using dynamic inventory, which host is the 'first' may not be consistent, so you wouldn't want to do this unless your inventory -was static and predictable. (If you are using :doc:`tower`, it will use database order, so this isn't a problem even if you are using cloud +is static and predictable. (If you are using :doc:`tower`, it will use database order, so this isn't a problem even if you are using cloud based inventory scripts). Anyway, here's the trick: @@ -252,7 +252,7 @@ Notice how we interchanged the bracket syntax for dots -- that can be done anywh How do I copy files recursively onto a target host? +++++++++++++++++++++++++++++++++++++++++++++++++++ -The "copy" module has a recursive parameter, though if you want to do something more efficient for a large number of files, take a look at the "synchronize" module instead, which wraps rsync. See the module index for info on both of these modules. +The "copy" module has a recursive parameter. However, take a look at the "synchronize" module if you want to do something more efficient for a large number of files. The "synchronize" module wraps rsync. See the module index for info on both of these modules. .. _shell_env: @@ -260,7 +260,7 @@ How do I access shell environment variables? ++++++++++++++++++++++++++++++++++++++++++++ If you just need to access existing variables, use the 'env' lookup plugin. For example, to access the value of the HOME -environment variable on management machine:: +environment variable on the management machine:: --- # ... @@ -269,7 +269,7 @@ environment variable on management machine:: If you need to set environment variables, see the Advanced Playbooks section about environments. -Ansible 1.4 will also make remote environment variables available via facts in the 'ansible_env' variable: +Starting with Ansible 1.4, remote environment variables are available via facts in the 'ansible_env' variable: .. code-block:: jinja @@ -325,7 +325,7 @@ and easy to use. See :doc:`tower`. How do I submit a change to the documentation? ++++++++++++++++++++++++++++++++++++++++++++++ -Great question! Documentation for Ansible is kept in the main project git repository, and complete instructions for contributing can be found in the docs README `viewable on GitHub `_. Thanks! +Great question! Documentation for Ansible is kept in the main project git repository, and complete instructions for contributing can be found in the docs README `viewable on GitHub `_. Thanks! .. _keep_secret_data: @@ -364,7 +364,7 @@ A steadfast rule is 'always use {{ }} except when `when:`'. Conditionals are always run through Jinja2 as to resolve the expression, so `when:`, `failed_when:` and `changed_when:` are always templated and you should avoid adding `{{}}`. -In most other cases you should always use the brackets, even if previouslly you could use variables without specifying (like `with_` clauses), +In most other cases you should always use the brackets, even if previously you could use variables without specifying (like `with_` clauses), as this made it hard to distinguish between an undefined variable and a string. Another rule is 'moustaches don't stack'. We often see this: