Adding some labels so we don't get "#id22" for the links in the docs.

pull/4367/merge
Michael DeHaan 11 years ago
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…
Cancel
Save