mirror of
https://github.com/ansible-collections/community.general.git
synced 2025-10-04 23:44:00 -07:00
Fix all RST errors for docs/docsite/rst (#20005)
* 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
Toshio Kuratomi
parent
cba66dfedc
commit
7df31aaca1
38 changed files with 464 additions and 1096 deletions
|
|
@ -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
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue