Rename 'yamlscripts' to 'yamlsyntax', add some extra crosslinking to make sure folks find the

interesting docs pages, some misc editing here and there.
This commit is contained in:
Michael DeHaan 2012-03-11 15:34:21 -04:00
commit d3fe5f617a
22 changed files with 219 additions and 165 deletions

View file

@ -1,83 +0,0 @@
YAML Format
===========
This page provides a basic overview of correct YAML syntax, which is how Ansible
playbooks (our configuration management language) are expressed.
You may also wish to read playbook examples and will quickly pick this up from those.
YAML Basics
-----------
For `ansible`, every YAML file must be a list at it's root-most
element. Each item in the list is a dictionary. These dictionaries
represent all the options you can use to write an `ansible` file. In
addition, all YAML files (regardless of their association with
`ansible` or not) should start with ``---``.
In YAML a list can be represented in two ways. In one way all members
of a list are lines beginning at the same indentation level starting
with a ``-`` character::
---
# A list of tasty fruits
- Apple
- Orange
- Strawberry
- Mango
In the second way a list is represented as comma separated elements
surrounded by square brackets. Newlines are permitted between
elements::
---
# A list of tasty fruits
[apple, orange, banana, mango]
A dictionary is represented in a simple ``key:`` and ``value`` form::
---
# An employee record
name: John Eckersberg
job: Developer
skill: Elite
Like lists, dictionaries can be represented in an abbreviated form::
---
# An employee record
{name: John Eckersberg, job: Developer, skill: Elite}
.. _truthiness:
You can specify a boolean value (true/false) in several forms::
---
knows_oop: True
likes_emacs: TRUE
uses_cvs: false
Finally, you can combine these data structures::
---
# An employee record
name: John Eckersberg
job: Developer
skill: Elite
employed: True
foods:
- Apple
- Orange
- Strawberry
- Mango
languages:
ruby: Elite
python: Elite
dotnet: Lame
That's all you really need to know about YAML to get started writing
`Ansible` playbooks.
.. seealso::
`YAMLLint <http://yamllint.com/>`_
YAML Lint gets the lint out of your YAML

94
rst/YAMLSyntax.rst Normal file
View file

@ -0,0 +1,94 @@
YAML Syntax
===========
This page provides a basic overview of correct YAML syntax, which is how Ansible
playbooks (our configuration management language) are expressed.
We use YAML because it is easier to read and write for humans than other common
data formats like XML or JSON. Further, there are libraries available for reading
and writing YAML in most programming languages.
You may also wish to read playbook examples at the same time to see how this
is used in practice.
.. seealso::
:doc:`playbooks`
See YAML examples in practice in playbooks
YAML Basics
-----------
For `ansible`, every YAML file starts with a list of things
to do. Each item in the list is a list of key/value pairs, commonly
called a "hash" or a "dictionary". So, we need to know how
to write lists and dictionaries in YAML.
There's another small quirk to YAML. All YAML files (regardless of their association with
`ansible` or not) should start with ``---``. This is just a YAML
format thing that means "this is the start of a document".
All members of a list are lines beginning at the same indentation level starting
with a ``-`` (dash) character::
---
# A list of tasty fruits
- Apple
- Orange
- Strawberry
- Mango
A dictionary is represented in a simple ``key:`` and ``value`` form::
---
# An employee record
name: John Eckersberg
job: Developer
skill: Elite
Dictionaries can also be represented in an abbreviated form if you really want to::
---
# An employee record
{name: John Eckersberg, job: Developer, skill: Elite}
.. _truthiness:
Ansible doesn't really use these too much, but you can also specify a
boolean value (true/false) in several forms::
---
knows_oop: True
likes_emacs: TRUE
uses_cvs: false
Let's combine what we learned so far in an arbitary YAML example. This really
has nothing to do with Ansible, but will give you a feel for the format::
---
# An employee record
name: John Eckersberg
job: Developer
skill: Elite
employed: True
foods:
- Apple
- Orange
- Strawberry
- Mango
languages:
ruby: Elite
python: Elite
dotnet: Lame
That's all you really need to know about YAML to get started writing
`Ansible` playbooks.
.. seealso::
:doc:`playbooks`
Learn what playbooks can do and how to write/run them.
`YAMLLint <http://yamllint.com/>`_
YAML Lint (online) helps you debug YAML syntax if you are having problems

View file

@ -181,3 +181,10 @@ It also excels for writing distributed
scripts and ad-hoc applications that need to gather data or perform arbitrary
tasks -- whether for a QA sytem, build system, or anything you can think of.
.. seealso::
:doc:`examples`
Examples of basic commands
:doc:`playbooks`
Learning ansible's configuration management language

View file

@ -99,13 +99,16 @@ Now run a live command on all of your nodes::
ansible all /bin/echo hello
Congratulations. You've just contacted your nodes with Ansible. It's
now time to read some of the more real-world examples, and explore
now time to read some of the more real-world :doc:`examples`, and explore
what you can do with different modules, as well as the Ansible
playbooks language. Ansible is not just about running commands, but
:doc:`playbooks` language. Ansible is not just about running commands, but
you already have a working infrastructure!
.. seealso::
:ref:`Inventory <inventoryformat>`
Complete documentation on the inventory file format
:doc:`examples`
Examples of basic commands
:doc:`playbooks`
Learning ansible's configuration management language

View file

@ -88,7 +88,7 @@ Contents
patterns
examples
modules
YAMLScripts
YAMLSyntax
playbooks
api
faq

View file

@ -34,6 +34,8 @@ looks like this::
two.example.com
three.example.com
The things in brackets are group names, you don't have to have them,
but they are useful.
Selecting Targets
+++++++++++++++++
@ -43,19 +45,20 @@ These patterns target all hosts in the inventory file::
all
*
It is also possible to address specific hosts::
Basically 'all' is an alias for '*'. It is also possible to address a specific host or hosts::
one.example.com
one.example.com:two.example.com
192.168.1.50
192.168.1.*
The following patterns address one or more groups, which are denoted
with the bracket headers in the inventory file::
with the aforementioned bracket headers in the inventory file::
webservers
webservers:dbservers
Individual hosts, but not groups, can also be referenced using
Individual host names (or IPs), but not groups, can also be referenced using
wildcards::
*.example.com
@ -66,4 +69,8 @@ It's also ok to mix wildcard patterns and groups at the same time::
one*.com:dbservers
.. note::
It is not possible to target a host not in the inventory file.
It is not possible to target a host not in the inventory file. This is a safety feature.
Easy enough. Now see :doc:`examples` and then :doc:`playbooks` for how to do things to selected hosts.

View file

@ -3,7 +3,7 @@ Playbooks
.. seealso::
:doc:`YAMLScripts`
:doc:`YAMLSyntax`
Learn about YAML syntax
:doc:`modules`
Learn about available modules and writing your own