Adding some labels so we don't get "#id22" for the links in the docs.
parent
a74c0091b2
commit
198c9a5903
|
@ -9,6 +9,8 @@ API so you have a considerable amount of power across the board. This chapter d
|
|||
.. contents:: `Table of contents`
|
||||
:depth: 2
|
||||
|
||||
.. _python_api:
|
||||
|
||||
Python API
|
||||
----------
|
||||
|
||||
|
@ -43,6 +45,8 @@ expressed in the 'ansible-modules' documentation.::
|
|||
A module can return any type of JSON data it wants, so Ansible can
|
||||
be used as a framework to rapidly build powerful applications and scripts.
|
||||
|
||||
.. _detailed_api_example:
|
||||
|
||||
Detailed API Example
|
||||
````````````````````
|
||||
|
||||
|
|
|
@ -8,6 +8,8 @@ How do we write a new one?
|
|||
Simple! We just create a script or program that can return JSON in the right format when fed the proper arguments.
|
||||
You can do this in any language.
|
||||
|
||||
.. _inventory_script_conventions:
|
||||
|
||||
Script Conventions
|
||||
``````````````````
|
||||
|
||||
|
@ -46,6 +48,8 @@ if the script does not wish to do this, returning an empty hash/dictionary is th
|
|||
"monitoring" : "pack.example.com"
|
||||
}
|
||||
|
||||
.. _inventory_script_tuning:
|
||||
|
||||
Tuning the External Inventory Script
|
||||
````````````````````````````````````
|
||||
|
||||
|
|
|
@ -11,8 +11,11 @@ by `ANSIBLE_LIBRARY` or the ``--module-path`` command line option.
|
|||
:depth: 2
|
||||
|
||||
|
||||
.. _module_dev_tutorial:
|
||||
|
||||
Tutorial
|
||||
````````
|
||||
|
||||
Let's build a module to get and set the system time. For starters, let's build
|
||||
a module that just outputs the current time.
|
||||
|
||||
|
@ -45,6 +48,8 @@ Ok, let's get going with an example. We'll use Python. For starters, save this
|
|||
"time" : date
|
||||
})
|
||||
|
||||
.. _module_testing:
|
||||
|
||||
Testing Modules
|
||||
```````````````
|
||||
|
||||
|
@ -63,6 +68,8 @@ You should see output that looks something like this::
|
|||
|
||||
If you did not, you might have a typo in your module, so recheck it and try again.
|
||||
|
||||
.. _reading_input:
|
||||
|
||||
Reading Input
|
||||
`````````````
|
||||
|
||||
|
@ -176,6 +183,8 @@ This should return something like::
|
|||
|
||||
{"changed": true, "time": "2012-03-14 12:23:00.000307"}
|
||||
|
||||
.. _module_provided_facts:
|
||||
|
||||
Module Provided 'Facts'
|
||||
```````````````````````
|
||||
|
||||
|
@ -199,6 +208,8 @@ These 'facts' will be available to all statements called after that module (but
|
|||
A good idea might be make a module called 'site_facts' and always call it at the top of each playbook, though
|
||||
we're always open to improving the selection of core facts in Ansible as well.
|
||||
|
||||
.. _common_module_boilerplate:
|
||||
|
||||
Common Module Boilerplate
|
||||
`````````````````````````
|
||||
|
||||
|
@ -248,6 +259,8 @@ can function outside of Ansible.
|
|||
If submitting a module to ansible's core code, which we encourage, use of the AnsibleModule
|
||||
class is required.
|
||||
|
||||
.. _developing_for_check_mode:
|
||||
|
||||
Check Mode
|
||||
``````````
|
||||
.. versionadded:: 1.1
|
||||
|
@ -274,6 +287,8 @@ system state is altered when the user enables check mode.
|
|||
If your module does not support check mode, when the user runs Ansible in check
|
||||
mode, your module will simply be skipped.
|
||||
|
||||
.. _module_dev_pitfalls:
|
||||
|
||||
Common Pitfalls
|
||||
```````````````
|
||||
|
||||
|
@ -295,6 +310,8 @@ will still be shown in Ansible, but the command will not succeed.
|
|||
Always use the hacking/test-module script when developing modules and it will warn
|
||||
you about these kind of things.
|
||||
|
||||
.. _module_dev_conventions:
|
||||
|
||||
Conventions/Recommendations
|
||||
```````````````````````````
|
||||
|
||||
|
@ -321,6 +338,8 @@ and guidelines:
|
|||
|
||||
* As results from many hosts will be aggregrated at once, modules should return only relevant output. Returning the entire contents of a log file is generally bad form.
|
||||
|
||||
.. _module_dev_shorthand:
|
||||
|
||||
Shorthand Vs JSON
|
||||
`````````````````
|
||||
|
||||
|
@ -334,6 +353,7 @@ will know what to do::
|
|||
If you're writing a module in Python or Ruby or whatever, though, returning
|
||||
JSON is probably the simplest way to go.
|
||||
|
||||
.. _module_documenting:
|
||||
|
||||
Documenting Your Module
|
||||
```````````````````````
|
||||
|
@ -344,6 +364,8 @@ which conforms to the schema defined below. You may find it easier to
|
|||
start writing your ``DOCUMENTATION`` string in an editor with YAML
|
||||
syntax highlighting before you include it in your Python file.
|
||||
|
||||
.. _module_doc_example:
|
||||
|
||||
Example
|
||||
+++++++
|
||||
|
||||
|
@ -384,6 +406,8 @@ The ``module_formatter.py`` script and ``ansible-doc(1)`` append the
|
|||
``EXAMPLES`` blob after any existing (deprecated) ``examples`` you may have in the
|
||||
YAML ``DOCUMENTATION`` string.
|
||||
|
||||
.. _module_dev_testing:
|
||||
|
||||
Building & Testing
|
||||
++++++++++++++++++
|
||||
|
||||
|
@ -418,6 +442,8 @@ output formats available:
|
|||
You can use ANSIBLE_KEEP_REMOTE_FILES=1 to prevent ansible from
|
||||
deleting the remote files so you can debug your module.
|
||||
|
||||
.. _module_contribution:
|
||||
|
||||
Getting Your Module Into Core
|
||||
`````````````````````````````
|
||||
|
||||
|
@ -425,7 +451,8 @@ High-quality modules with minimal dependencies
|
|||
can be included in the core, but core modules (just due to the programming
|
||||
preferences of the developers) will need to be implemented in Python and use
|
||||
the AnsibleModule common code, and should generally use consistent arguments with the rest of
|
||||
the program. Stop by the mailing list to inquire about requirements.
|
||||
the program. Stop by the mailing list to inquire about requirements if you like, and submit
|
||||
a github pull request to the main project.
|
||||
|
||||
.. seealso::
|
||||
|
||||
|
|
Loading…
Reference in New Issue