internet/community.general
3
0
Fork 0
mirror of https://github.com/ansible-collections/community.general.git synced 2026-05-07 05:42:50 +00:00
Code Issues Packages Projects Releases Wiki Activity

Fix all RST errors for docs/docsite/rst (#20005)

Browse Source 
* developing_modules.rst is now in dev_guide, sync changes and delete the old version
* Cleaner RST & formatted code
* Tidyup roadmaps
* Link to repomerge
* Pull in abadger's fixes From https://github.com/ansible/ansible/compare/docs-code-block-fixes?expand=1
* Clean docsite/rst (apart from ROADMAP
This commit is contained in:
John R Barker
2017-01-07 19:38:52 +00:00
committed by Toshio Kuratomi
parent cba66dfedc
commit 7df31aaca1
38 changed files with 464 additions and 1096 deletions
Download Patch File Download Diff File Expand all files Collapse all files

18
docs/docsite/rst/dev_guide/developing.rst
View File

@@ -1,18 +0,0 @@
Developer Information
`````````````````````
Learn how to build modules of your own in any language, and also how to extend Ansible through several kinds of plugins. Explore Ansible's Python API and write Python plugins to integrate with other solutions in your environment.
.. toctree::
:maxdepth: 1
developing_api
developing_inventory
developing_modules
developing_plugins
developing_core
developing_test_pr
developing_releases
Developers will also likely be interested in the fully-discoverable in :doc:`tower`. It's great for embedding Ansible in all manner of applications.

4
docs/docsite/rst/dev_guide/developing_api.rst
View File

@@ -16,7 +16,7 @@ write various plugins, and you can plug in inventory data from external data sou
covers the execution and Playbook API at a basic level.
If you are looking to use Ansible programmatically from something other than Python, trigger events asynchronously,
or have access control and logging demands, take a look at :doc:`tower`
or have access control and logging demands, take a look at :doc:`../tower`
as it has a very nice REST API that provides all of these things at a higher level.
Ansible is written in its own API so you have a considerable amount of power across the board.
@@ -125,7 +125,7 @@ It's pretty simple::
The run method returns results per host, grouped by whether they
could be contacted or not. Return types are module specific, as
expressed in the :doc:`modules` documentation.::
expressed in the :doc:`../modules` documentation.::
{
"dark" : {

2
docs/docsite/rst/dev_guide/developing_inventory.rst
View File

@@ -4,7 +4,7 @@ Developing Dynamic Inventory Sources
.. contents:: Topics
:local:
As described in :doc:`intro_dynamic_inventory`, ansible can pull inventory information from dynamic sources, including cloud sources.
As described in :doc:`../intro_dynamic_inventory`, Ansible can pull inventory information from dynamic sources, including cloud sources.
How do we write a new one?

197
docs/docsite/rst/dev_guide/developing_modules.rst
View File

@@ -9,7 +9,7 @@ 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
as we work through this tutorial.
See :doc:`modules` for a list of various ones developed in core.
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.
@@ -51,7 +51,9 @@ modules. Keep in mind, though, that some modules in Ansible's source tree are
so look at :ref:`service` or :ref:`yum`, and don't stare too close into things like ``async_wrapper`` or
you'll turn to stone. Nobody ever executes ``async_wrapper`` directly.
Ok, let's get going with an example. We'll use Python. For starters, save this as a file named :file:`timetest.py`::
Ok, let's get going with an example. We'll use Python. For starters, save this as a file named :file:`timetest.py`
.. code-block:: python
#!/usr/bin/python
@@ -68,21 +70,27 @@ Ok, let's get going with an example. We'll use Python. For starters, save this
Testing Modules
````````````````
There's a useful test script in the source checkout for Ansible::
There's a useful test script in the source checkout for Ansible:
.. code-block:: shell-session
git clone git://github.com/ansible/ansible.git --recursive
source ansible/hacking/env-setup
For instructions on setting up Ansible from source, please see
:doc:`intro_installation`.
:doc:`../intro_installation`.
Let's run the script you just wrote with that::
Let's run the script you just wrote with that:
.. code-block:: shell-session
ansible/hacking/test-module -m ./timetest.py
You should see output that looks something like this::
You should see output that looks something like this:
{'time': '2012-03-14 22:13:48.539183'}
.. code-block:: json
{"time": "2012-03-14 22:13:48.539183"}
If you did not, you might have a typo in your module, so recheck it and try again.
@@ -111,7 +119,9 @@ If no time parameter is set, we'll just leave the time as is and return the curr
Let's look at the code. Read the comments as we'll explain as we go. Note that this
is highly verbose because it's intended as an educational example. You can write modules
a lot shorter than this::
a lot shorter than this:
.. code-block:: python
#!/usr/bin/python
@@ -211,7 +221,9 @@ Binary Modules Input
Support for binary modules was added in Ansible 2.2. When Ansible detects a binary module, it will proceed to
supply the argument input as a file on ``argv[1]`` that is formatted as JSON. The JSON contents of that file
would resemble something similar to the following payload for a module accepting the same arguments as the
``ping`` module::
``ping`` module:
.. code-block:: json
{
"data": "pong",
@@ -229,10 +241,12 @@ Module Provided 'Facts'
The :ref:`setup` module that ships with Ansible provides many variables about a system that can be used in playbooks
and templates. However, it's possible to also add your own facts without modifying the system module. To do
this, just have the module return a `ansible_facts` key, like so, along with other return data::
this, just have the module return a `ansible_facts` key, like so, along with other return data:
.. code-block:: json
{
"changed" : True,
"changed" : true,
"rc" : 5,
"ansible_facts" : {
"leptons" : 5000,
@@ -265,7 +279,9 @@ Rather than mention these here, the best way to learn is to read some of the `so
The 'group' and 'user' modules are reasonably non-trivial and showcase what this looks like.
Key parts include always importing the boilerplate code from
:mod:`ansible.module_utils.basic` like this::
:mod:`ansible.module_utils.basic` like this:
.. code-block:: python
from ansible.module_utils.basic import AnsibleModule
if __name__ == '__main__':
@@ -274,11 +290,15 @@ Key parts include always importing the boilerplate code from
.. note::
Prior to Ansible-2.1.0, importing only what you used from
:mod:`ansible.module_utils.basic` did not work. You needed to use
a wildcard import like this::
a wildcard import like this:
.. code-block:: python
from ansible.module_utils.basic import *
And instantiating the module class like::
And instantiating the module class like:
.. code-block:: python
def main():
module = AnsibleModule(
@@ -293,11 +313,15 @@ And instantiating the module class like::
The :class:`AnsibleModule` provides lots of common code for handling returns, parses your arguments
for you, and allows you to check inputs.
Successful returns are made like this::
Successful returns are made like this:
.. code-block:: python
module.exit_json(changed=True, something_else=12345)
And failures are just as simple (where `msg` is a required parameter to explain the error)::
And failures are just as simple (where `msg` is a required parameter to explain the error):
.. code-block:: python
module.fail_json(msg="Something fatal happened")
@@ -322,7 +346,9 @@ mode, the module should try to predict whether changes will occur.
For your module to support check mode, you must pass ``supports_check_mode=True``
when instantiating the AnsibleModule object. The AnsibleModule.check_mode attribute
will evaluate to True when check mode is enabled. For example::
will evaluate to True when check mode is enabled. For example:
.. code-block:: python
module = AnsibleModule(
argument_spec = dict(...),
@@ -344,7 +370,9 @@ mode, your module will simply be skipped.
Common Pitfalls
```````````````
You should also never do this in a module::
You should also NEVER do this in a module:
.. code-block:: python
print "some status message"
@@ -358,6 +386,12 @@ 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.
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.
Avoid creating 'caches'. Ansible is designed without a central server or authority, so you cannot guarantee it will not run with different permissions, options or locations. If you need a central authority, have it on top of Ansible (for example, using bastion/cm/ci server or tower); do not try to build it into modules.
Always use the hacking/test-module script when developing modules and it will warn
you about these kind of things.
@@ -407,7 +441,9 @@ Example
See an example documentation string in the checkout under `examples/DOCUMENTATION.yml <https://github.com/ansible/ansible/blob/devel/examples/DOCUMENTATION.yml>`_.
Include it in your module file like this::
Include it in your module file like this:
.. code-block:: python
#!/usr/bin/python
# Copyright header....
@@ -419,8 +455,6 @@ Include it in your module file like this::
# ... snip ...
'''
If an argument takes both C(True)/C(False) and C(Yes)/C(No), the documentation should use C(True) and C(False).
The ``description``, and ``notes`` fields
support formatting with some special macros.
@@ -451,17 +485,17 @@ the ``copy`` module::
description: destination file/path
returned: success
type: string
sample: "/path/to/file.txt"
sample: /path/to/file.txt
src:
description: source file used for the copy on the target machine
returned: changed
type: string
sample: "/home/httpd/.ansible/tmp/ansible-tmp-1423796390.97-147729857856000/source"
sample: /home/httpd/.ansible/tmp/ansible-tmp-1423796390.97-147729857856000/source
md5sum:
description: md5 checksum of the file after running copy
returned: when supported
type: string
sample: "2a5aeecc61dc98c4d780b14b330e3282"
sample: 2a5aeecc61dc98c4d780b14b330e3282
...
'''
@@ -507,7 +541,9 @@ some helper methods to do just that.
If you are using Ansible with the :envvar:`ANSIBLE_KEEP_REMOTE_FILES`
environment variables to keep the remote module file, here's a sample of how
your debugging session will start::
your debugging session will start:
.. code-block:: sh
$ ANSIBLE_KEEP_REMOTE_FILES=1 ansible localhost -m ping -a 'data=debugging_session' -vvv
<127.0.0.1> ESTABLISH LOCAL CONNECTION FOR USER: badger
@@ -515,13 +551,13 @@ your debugging session will start::
<127.0.0.1> PUT /var/tmp/tmpjdbJ1w TO /home/badger/.ansible/tmp/ansible-tmp-1461434734.35-235318071810595/ping
<127.0.0.1> EXEC /bin/sh -c 'LANG=en_US.UTF-8 LC_ALL=en_US.UTF-8 LC_MESSAGES=en_US.UTF-8 /usr/bin/python /home/badger/.ansible/tmp/ansible-tmp-1461434734.35-235318071810595/ping'
localhost | SUCCESS => {
"changed": false,
"changed": false,
"invocation": {
"module_args": {
"data": "debugging_session"
},
},
"module_name": "ping"
},
},
"ping": "debugging_session"
}
@@ -533,7 +569,9 @@ 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
script with a large, base64 encoded string. The string contains the module
that is going to be executed. Run the wrapper's explode command to turn the
string into some python files that you can work with::
string into some python files that you can work with:
.. code-block:: shell-session
$ python /home/badger/.ansible/tmp/ansible-tmp-1461434734.35-235318071810595/ping explode
Module expanded into:
@@ -571,7 +609,9 @@ When you look into the debug_dir you'll see a directory structure like this::
the module code you have written.
Once you edit the code or arguments in the exploded tree you need some way to
run it. There's a separate wrapper subcommand for this::
run it. There's a separate wrapper subcommand for this:
.. code-block:: shell-session
$ python /home/badger/.ansible/tmp/ansible-tmp-1461434734.35-235318071810595/ping execute
{"invocation": {"module_args": {"data": "debugging_session"}}, "changed": false, "ping": "debugging_session"}
@@ -639,16 +679,18 @@ The following checklist items are important guidelines for people who want to c
* Modules must be written to support Python 2.4. If this is not possible, required minimum python version and rationale should be explained in the requirements section in ``DOCUMENTATION``. This minimum requirement will be advanced to Python-2.6 in Ansible-2.4.
* Modules must be written to use proper Python-3 syntax. At some point in the future we'll come up with rules for running on Python-3 but we're not there yet. See :doc:`developing_modules_python3` for help on how to do this.
* Modules must have a metadata section. For the vast majority of new modules,
the metadata should look exactly like this::
the metadata should look exactly like this:
.. code-block:: python
ANSIBLE_METADATA = {'status': ['preview'],
'supported_by': 'community',
'version': '1.0'}
The complete module metadata specification is here: https://github.com/ansible/proposals/issues/30
The complete module metadata specification is here: https://github.com/ansible/proposals/issues/30
* Documentation: Make sure it exists
* Module documentation should briefly and accurately define what each module and option does, and how it works with others in the underlying system. Documentation should be written for broad audience--readable both by experts and non-experts. This documentation is not meant to teach a total novice, but it also should not be reserved for the Illuminati (hard balance).
* If an argument takes both C(True)/C(False) and C(Yes)/C(No), the documentation should use C(True) and C(False).
* Descriptions should always start with a capital letter and end with a full stop. Consistency always helps.
* The `required` setting is only required when true, otherwise it is assumed to be false.
* If `required` is false/missing, `default` may be specified (assumed 'null' if missing). Ensure that the default parameter in docs matches default parameter in code.
@@ -682,7 +724,7 @@ The following checklist items are important guidelines for people who want to c
* Fail predictably--if we must fail, do it in a way that is the most expected. Either mimic the underlying tool or the general way the system works.
* Modules should not do the job of other modules, that is what roles are for. Less magic is more.
* Don't reinvent the wheel. Part of the problem is that code sharing is not that easy nor documented, we also need to expand our base functions to provide common patterns (retry, throttling, etc).
* Support check mode. This is not required for all modules, as it won't make sense for certain ones, but please attempt to include this when applicable). For more information, refer to :ref:`check_mode_drift` and :ref:`check_mode_dry`.
* Support check mode. This is not required for all modules, as it won't make sense for certain ones, but please attempt to include this when applicable). For more information, refer to :ref:`check_mode_drift` and :ref:`check_mode_dry`.
* Exceptions: The module must handle them. (exceptions are bugs)
* Give out useful messages on what you were doing and you can add the exception message to that.
* Avoid catchall exceptions, they are not very useful unless the underlying API gives very good error messages pertaining the attempted action.
@@ -696,7 +738,9 @@ The following checklist items are important guidelines for people who want to c
- ec2
* The module must not use sys.exit() --> use fail_json() from the module object.
* Import custom packages in try/except and handled with fail_json() in main() e.g.::
* Import custom packages in try/except and handled with fail_json() in main() e.g.
.. code-block:: python
try:
import foo
@@ -710,7 +754,9 @@ The following checklist items are important guidelines for people who want to c
* Do not use wildcards for importing other python modules (ex: ``from ansible.module_utils.basic import *``). This used to be required for code imported from ``ansible.module_utils`` but, from Ansible-2.1 onwards, it's just an outdated and bad practice.
* The module must have a `main` function that wraps the normal execution.
* Call your :func:`main` from a conditional so that it would be possible to
import them into unittests in the future example::
import them into unittests in the future example
.. code-block:: python
if __name__ == '__main__':
main()
@@ -727,53 +773,80 @@ The following checklist items are important guidelines for people who want to c
fields of a dictionary and return the dictionary.
* When fetching URLs, please use either fetch_url or open_url from ansible.module_utils.urls
rather than urllib2; urllib2 does not natively verify TLS certificates and so is insecure for https.
* facts modules must return facts in the ansible_facts field of the result
dictionary. :ref:`module_provided_facts`
* modules that are purely about fact gathering need to implement check_mode.
they should not cause any changes anyway so it should be as simple as adding
check_mode=True when instantiating AnsibleModule. (The reason is that
playbooks which conditionalize based on fact information will only
conditionalize correctly in check_mode if the facts are returned in
check_mode).
* Basic auth: module_utils.api has some helpers for doing basic auth with
module_utils.urls.fetch_url(). If you use those you may find you also want
to fallback on environment variables for default values. If you do that,
be sure to use non-generic environment variables (like
:envvar:`API_<MODULENAME>_USERNAME`). Using generic environment variables
like :envvar:`API_USERNAME` would conflict between modules.
Windows modules checklist
`````````````````````````
* Favour native powershell and .net ways of doing things over calls to COM libraries or calls to native executables which may or may not be present in all versions of windows
* Favour native powershell and .net ways of doing things over calls to COM libraries or calls to native executables which may or may not be present in all versions of Windows
* modules are in powershell (.ps1 files) but the docs reside in same name python file (.py)
* look at ansible/lib/ansible/module_utils/powershell.ps1 for common code, avoid duplication
* Ansible uses strictmode version 2.0 so be sure to test with that enabled
* start with::
All powershell modules must start:
.. code-block:: powershell
#!powershell
then::
<GPL header>
then::
# WANT_JSON
# POWERSHELL_COMMON
then, to parse all arguments into a variable modules generally use::
To parse all arguments into a variable modules generally use:
.. code-block:: powershell
$params = Parse-Args $args
* Arguments:
* Try and use state present and state absent like other modules
* You need to check that all your mandatory args are present. You can do this using the builtin Get-AnsibleParam function.
* Required arguments::
Arguments
+++++++++
* Try and use state present and state absent like other modules
* You need to check that all your mandatory args are present. You can do this using the builtin Get-AnsibleParam function.
* Required arguments:
.. code-block:: powershell
$package = Get-AnsibleParam -obj $params -name name -failifempty $true
* Required arguments with name validation::
Required arguments with name validation:
.. code-block:: powershell
$state = Get-AnsibleParam -obj $params -name "State" -ValidateSet "Present","Absent" -resultobj $resultobj -failifempty $true
* Optional arguments with name validation::
Optional arguments with name validation
+++++++++++++++++++++++++++++++++++++++
.. code-block:: powershell
$state = Get-AnsibleParam -obj $params -name "State" -default "Present" -ValidateSet "Present","Absent"
* the If "FailIfEmpty" is true, the resultobj parameter is used to specify the object returned to fail-json. You can also override the default message
using $emptyattributefailmessage (for missing required attributes) and $ValidateSetErrorMessage (for attribute validation errors)
* Look at existing modules for more examples of argument checking.
* If the "FailIfEmpty" is true, the resultobj parameter is used to specify the object returned to fail-json. You can also override the default message
using $emptyattributefailmessage (for missing required attributes) and $ValidateSetErrorMessage (for attribute validation errors)
* Look at existing modules for more examples of argument checking.
* Results
* The result object should always contain an attribute called changed set to either $true or $false
* Create your result object like this::
Results
+++++++
* The result object should always contain an attribute called changed set to either $true or $false
* Create your result object like this
.. code-block:: powershell
$result = New-Object psobject @{
changed = $false
@@ -783,10 +856,10 @@ Windows modules checklist
If all is well, exit with a
Exit-Json $result
* Ensure anything you return, including errors can be converted to json.
* Be aware that because exception messages could contain almost anything.
* ConvertTo-Json will fail if it encounters a trailing \ in a string.
* If all is not well use Fail-Json to exit.
* Ensure anything you return, including errors can be converted to json.
* Be aware that because exception messages could contain almost anything.
* ConvertTo-Json will fail if it encounters a trailing \ in a string.
* If all is not well use Fail-Json to exit.
* Have you tested for powershell 3.0 and 4.0 compliance?
@@ -808,7 +881,7 @@ This example allows the stat module to be called with fileinfo, making the follo
.. seealso::
:doc:`modules`
:doc:`../modules`
Learn about available modules
:doc:`developing_plugins`
Learn about developing plugins

43
docs/docsite/rst/dev_guide/developing_plugins.rst
View File

@@ -76,17 +76,21 @@ You can only have one plugin be the main manager of your console output. If you
Developing Callback Plugins
+++++++++++++++++++++++++++
Callback plugins are created by creating a new class with the Base(Callbacks) class as the parent::
Callback plugins are created by creating a new class with the Base(Callbacks) class as the parent:
.. code-block:: python
from ansible.plugins.callback import CallbackBase
from ansible import constants as C
class CallbackModule(CallbackBase):
class CallbackModule(CallbackBase):
From there, override the specific methods from the CallbackBase that you want to provide a callback for. For plugins intended for use with Ansible version 2.0 and later, you should only override methods that start with `v2`. For a complete list of methods that you can override, please see ``__init__.py`` in the `lib/ansible/plugins/callback <https://github.com/ansible/ansible/tree/devel/lib/ansible/plugins/callback>`_ directory.
The following example shows how Ansible's timer plugin is implemented::
The following example shows how Ansible's timer plugin is implemented:
.. code-block:: python
# Make coding more python3-ish
from __future__ import (absolute_import, division, print_function)
@@ -105,21 +109,21 @@ The following example shows how Ansible's timer plugin is implemented::
CALLBACK_TYPE = 'aggregate'
CALLBACK_NAME = 'timer'
CALLBACK_NEEDS_WHITELIST = True
def __init__(self):
super(CallbackModule, self).__init__()
self.start_time = datetime.now()
def days_hours_minutes_seconds(self, runtime):
minutes = (runtime.seconds // 60) % 60
r_seconds = runtime.seconds - (minutes * 60)
return runtime.days, runtime.seconds // 3600, minutes, r_seconds
def playbook_on_stats(self, stats):
self.v2_playbook_on_stats(stats)
def v2_playbook_on_stats(self, stats):
end_time = datetime.now()
runtime = end_time - self.start_time
@@ -132,9 +136,8 @@ Note that the CALLBACK_VERSION and CALLBACK_NAME definitions are required for pr
Connection Plugins
------------------
By default, ansible ships with a 'paramiko' SSH, native ssh (just called 'ssh'), 'local' connection type, and there are also some minor players like 'chroot' and 'jail'. All of these can be used in playbooks and with /usr/bin/ansible to decide how you want to talk to remote machines. The basics of these connection types
are covered in the :doc:`intro_getting_started` section. Should you want to extend Ansible to support other transports (SNMP? Message bus?
Carrier Pigeon?) it's as simple as copying the format of one of the existing modules and dropping it into the connection plugins
By default, Ansible ships with a 'paramiko' SSH, native ssh (just called 'ssh'), 'local' connection type, and there are also some minor players like 'chroot' and 'jail'. All of these can be used in playbooks and with /usr/bin/ansible to decide how you want to talk to remote machines. The basics of these connection types
are covered in the :doc:`../intro_getting_started` section. Should you want to extend Ansible to support other transports (SNMP, Message bus, etc) it's as simple as copying the format of one of the existing modules and dropping it into the connection plugins
directory. The value of 'smart' for a connection allows selection of paramiko or openssh based on system capabilities, and chooses
'ssh' if OpenSSH supports ControlPersist, in Ansible 1.2.1 and later. Previous versions did not support 'smart'.
@@ -145,9 +148,11 @@ More documentation on writing connection plugins is pending, though you can jump
Lookup Plugins
--------------
Lookup plugins are used to pull in data from external data stores. Lookup plugins can be used within playbooks for both looping - playbook language constructs like "with_fileglob" and "with_items" are implemented via lookup plugins - and to return values into a variable or parameter.
Lookup plugins are used to pull in data from external data stores. Lookup plugins can be used within playbooks for both looping - playbook language constructs like "with_fileglob" and "with_items" are implemented via lookup plugins - and to return values into a variable or parameter.
Here's a simple lookup plugin implementation - this lookup returns the contents of a text file as a variable::
Here's a simple lookup plugin implementation - this lookup returns the contents of a text file as a variable:
.. code-block:: python
from ansible.errors import AnsibleError, AnsibleParserError
from ansible.plugins.lookup import LookupBase
@@ -193,7 +198,9 @@ An example of how this lookup is called::
- debug: msg="the value of foo.txt is {{ contents }} as seen today {{ lookup('pipe', 'date +"%Y-%m-%d"') }}"
Errors encountered during execution should be returned by raising AnsibleError() with a message describing the error. Any strings returned by your lookup plugin implementation that could ever contain non-ASCII characters must be converted into Python's unicode type because the strings will be run through jinja2. To do this, you can use::
Errors encountered during execution should be returned by raising AnsibleError() with a message describing the error. Any strings returned by your lookup plugin implementation that could ever contain non-ASCII characters must be converted into Python's unicode type because the strings will be run through jinja2. To do this, you can use:
.. code-block:: python
from ansible.module_utils._text import to_text
result_string = to_text(result_string)
@@ -241,7 +248,7 @@ Distributing Plugins
Plugins are loaded from the library installed path and the configured plugins directory (check your `ansible.cfg`).
The location can vary depending on how you installed Ansible (pip, rpm, deb, etc) or by the OS/Distribution/Packager.
Plugins are automatically loaded when you have one of the following subfolders adjacent to your playbook or inside a role::
Plugins are automatically loaded when you have one of the following subfolders adjacent to your playbook or inside a role:
* action_plugins
* lookup_plugins
@@ -257,7 +264,7 @@ When shipped as part of a role, the plugin will be available as soon as the role
.. seealso::
:doc:`modules`
:doc:`../modules`
List of built-in modules
:doc:`developing_api`
Learn about the Python API for task execution

10
docs/docsite/rst/dev_guide/developing_program_flow_modules.rst
View File

@@ -86,11 +86,15 @@ JSONARGS
Scripts can arrange for an argument string to be placed within them by placing
the string ``<<INCLUDE_ANSIBLE_MODULE_JSON_ARGS>>`` somewhere inside of the
file. The module typically sets a variable to that value like this:: python
file. The module typically sets a variable to that value like this:
.. code-block:: python
json_arguments = """<<INCLUDE_ANSIBLE_MODULE_JSON_ARGS>>"""
Which is expanded as:: python
Which is expanded as:
.. code-block:: python
json_arguments = """{"param1": "test's quotes", "param2": "\"To be or not to be\" - Hamlet"}"""
@@ -458,7 +462,7 @@ this. If a module has to use this on its own, it should instantiate an
:attr:`AnsibleModule._syslog_facility`. The code will look slightly different
than it did under :ref:`module_replacer` due to how hacky the old way was
:: python
.. code-block:: python
# Old way
import syslog

47
docs/docsite/rst/dev_guide/developing_test_pr.rst
View File

@@ -116,7 +116,9 @@ For Those About To Test, We Salute You
At this point, you should be ready to begin testing!
If the PR is a bug-fix pull request, the first things to do are to run the suite of unit and integration tests, to ensure
the pull request does not break current functionality::
the pull request does not break current functionality:
.. code-block:: shell-session
# Unit Tests
make tests
@@ -139,16 +141,20 @@ We encourage users to provide playbook examples for bugs that show how to reprod
the issue if available. You may wish to also do your own review to poke the corners of the change.
Since some reproducers can be quite involved, you might wish to create a testing directory with the issue # as a sub-
directory to keep things organized::
directory to keep things organized:
.. code-block:: shell-session
mkdir -p testing/XXXX # where XXXX is again the issue # for the original issue or PR
cd testing/XXXX
<create files or git clone example playbook repo>
# create files or git clone example playbook repo
While it should go without saying, be sure to read any playbooks before you run them. VMs help with running untrusted content greatly,
though a playbook could still do something to your computing resources that you'd rather not like.
Once the files are in place, you can run the provided playbook (if there is one) to test the functionality::
Once the files are in place, you can run the provided playbook (if there is one) to test the functionality:
.. code-block:: shell-session
ansible-playbook -vvv playbook_name.yml
@@ -164,30 +170,29 @@ If the pull request resolves the issue, please leave a comment on the pull reque
In some cases, you may wish to share playbook output from the test run as well.
Example!::
Example!
Works for me! Tested on `Ansible 1.7.1`. I verified this on CentOS 6.5 and also Ubuntu 14.04.
| Works for me! Tested on `Ansible 1.7.1`. I verified this on CentOS 6.5 and also Ubuntu 14.04.
If the PR does not resolve the issue, or if you see any failures from the unit/integration tests, just include that output instead::
If the PR does not resolve the issue, or if you see any failures from the unit/integration tests, just include that output instead:
This doesn't work for me.
| This doesn't work for me.
|
| When I ran this Ubuntu 16.04 it failed with the following:
|
| BLARG
| StrackTrace
| RRRARRGGG
When I ran this my toaster started making loud noises!
When you are done testing a feature branch, you can remove it with the following command:
Output from the toaster looked like this:
.. code-block:: shell-session
```
BLARG
StrackTrace
RRRARRGGG
```
$ git branch -D someuser-feature_branch_name
When you are done testing a feature branch, you can remove it with the following command::
git branch -D someuser-feature_branch_name
We understand some users may be inexperienced with git, or other aspects of the above procedure, so feel free to stop by ansible-devel
list for questions and we'd be happy to help answer them.
We understand some users may be inexperienced with git, or other aspects of
the above procedure, so feel free to stop by ansible-devel list for questions
and we'd be happy to help answer them.

9
docs/docsite/rst/dev_guide/index.rst
View File

@@ -15,16 +15,15 @@ To get started, select one of the following topics.
:maxdepth: 1
overview_architecture
overview_components
overview_contributing
developing_modules
developing_modules_python3
developing_plugins
developing_inventory
developing_api
developing_module_utilities
developing_core
developing_test_pr
developing_rebasing
repomerge
developing_releases
../committer_guidelines

2
docs/docsite/rst/dev_guide/repomerge.rst
View File

@@ -30,6 +30,7 @@ The documentation pages for modules will be updated to reflect the above informa
.. _PRMover:
Move Issues and PRs to new Repo
-------------------------------
A tool has been developed to move a PR from the old repos to `ansible/ansible` this can be found at `prmover tool <https://prmover.pythonanywhere.com/>`_
@@ -41,3 +42,4 @@ To move issues please use `GitHub Issue Mover <https://github-issue-mover.appspo
If you have *any* issues with updating your PR please ask for support in `#ansible-devel`
For support please use `#ansible-devel` on Freenode IRC