cmueller/ansible
1
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

Various doc formatting fixes (#33626)

Browse source 
* Avoid italics from `with_`
* C() is for Modules, not for RST
* RST uses ``...`` for code
This commit is contained in:
John R Barker 2017-12-07 14:25:46 +00:00 committed by GitHub
parent 349099a4c6
commit c2bef76c46
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
3 changed files with 14 additions and 17 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

11
docs/docsite/rst/faq.rst
View file

@ -374,11 +374,11 @@ the :envvar:`ANSIBLE_DEBUG` environment variable.
When should I use {{ }}? Also, how to interpolate variables or dynamic variable names
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
A steadfast rule is 'always use {{ }} except when `when:`'.
A steadfast rule is 'always use ``{{ }}`` except when ``when:``'.
Conditionals are always run through Jinja2 as to resolve the expression,
so `when:`, `failed_when:` and `changed_when:` are always templated and you should avoid adding `{{}}`.
so ``when:``, ``failed_when:`` and ``changed_when:`` are always templated and you should avoid adding ``{{ }}``.
In most other cases you should always use the brackets, even if previously you could use variables without specifying (like `loop` or `with_` clauses),
In most other cases you should always use the brackets, even if previously you could use variables without specifying (like ``loop`` or ``with_`` clauses),
as this made it hard to distinguish between an undefined variable and a string.
Another rule is 'moustaches don't stack'. We often see this:
@ -393,16 +393,13 @@ The above DOES NOT WORK, if you need to use a dynamic variable use the hostvars
{{ hostvars[inventory_hostname]['somevar_' + other_var] }}
.. _i_dont_see_my_question:
Why don't you ship in X format?
+++++++++++++++++++++++++++++++
Several reasons, in most cases it has to do with maintainability, there are tons of ways to ship software and it is a herculean task to try to support them all.
In other cases there are technical issues, for example, for python wheels, our dependencies are not present so there is little to no gain.
.. _i_dont_see_my_question:
I don't see my question here
++++++++++++++++++++++++++++

18
docs/docsite/rst/playbooks_loops.rst
View file

@ -41,7 +41,7 @@ The above would be the equivalent of::
state: present
groups: "wheel"
.. note:: Before 2.5 Ansible mainly used the `with_<lookup>` keywords to create loops, the `loop` keyword is basically analogous to `with_list`.
.. note:: Before 2.5 Ansible mainly used the ``with_<lookup>`` keywords to create loops, the `loop` keyword is basically analogous to ``with_list``.
Some plugins like, the yum and apt modules can take lists directly to their options, this is more optimal than looping over the task.
@ -90,7 +90,7 @@ For example, using the 'nested' lookup, you can combine lists::
:doc:`Jinja2 lookups playbooks_lookups`, :doc:`filters playbooks_filters` and :doc:`tests playbooks_tests`
make for some powerful data generation and manipulation.
.. note:: `with_` loops are actually a combination of things `with_` + `lookup()`, even 'items' is a lookup. `loop` can be used in the same way as shown above.
.. note:: ``with_`` loops are actually a combination of things ``with_`` + ``lookup()``, even ``items`` is a lookup. ``loop`` can be used in the same way as shown above.
.. _do_until_loops:
@ -113,7 +113,7 @@ been retried for 5 times with a delay of 10 seconds. The default value for "retr
The task returns the results returned by the last task run. The results of individual retries can be viewed by -vv option.
The registered variable will also have a new key "attempts" which will have the number of the retries for the task.
.. note:: If the "until" parameter isn't defined, the value for the "retries" parameter is forced to 1.
.. note:: If the ``until`` parameter isn't defined, the value for the ``retries`` parameter is forced to 1.
Using register with a loop
``````````````````````````
@ -226,8 +226,8 @@ Loop Control
.. versionadded:: 2.1
In 2.0 you are again able to use loops and task includes (but not playbook includes). This adds the ability to loop over the set of tasks in one shot.
Ansible by default sets the loop variable `item` for each loop, which causes these nested loops to overwrite the value of `item` from the "outer" loops.
As of Ansible 2.1, the `loop_control` option can be used to specify the name of the variable to be used for the loop::
Ansible by default sets the loop variable ``item`` for each loop, which causes these nested loops to overwrite the value of ``item`` from the "outer" loops.
As of Ansible 2.1, the ``loop_control`` option can be used to specify the name of the variable to be used for the loop::
# main.yml
- include: inner.yml
@ -251,7 +251,7 @@ As of Ansible 2.1, the `loop_control` option can be used to specify the name of
.. versionadded:: 2.2
When using complex data structures for looping the display might get a bit too "busy", this is where the C(label) directive comes to help::
When using complex data structures for looping the display might get a bit too "busy", this is where the ``label`` directive comes to help::
- name: create servers
digital_ocean:
@ -272,7 +272,7 @@ This will now display just the 'label' field instead of the whole structure per
.. versionadded:: 2.2
Another option to loop control is C(pause), which allows you to control the time (in seconds) between execution of items in a task loop.::
Another option to loop control is ``pause``, which allows you to control the time (in seconds) between execution of items in a task loop.::
# main.yml
- name: create servers, pause 3s before creating next
@ -291,8 +291,8 @@ Another option to loop control is C(pause), which allows you to control the time
Loops and Includes in 2.0
`````````````````````````
Because `loop_control` is not available in Ansible 2.0, when using an include with a loop you should use `set_fact` to save the "outer" loops value
for `item`::
Because ``loop_control`` is not available in Ansible 2.0, when using an include with a loop you should use ``set_fact`` to save the "outer" loops value
for ``item``::
# main.yml
- include_tasks: inner.yml

2
docs/docsite/rst/playbooks_tests.rst
View file

@ -7,7 +7,7 @@ Tests
`Tests <http://jinja.pocoo.org/docs/dev/templates/#tests>`_ in Jinja are a way of evaluating template expressions and returning True or False.
Jinja ships with many of these. See `builtin tests`_ in the official Jinja template documentation.
The main difference between tests and filters are that Jinja tests are used for comparisons, whereas filters are used for data manipulation, and have different applications in jinja. Tests can also be used in list processing filters, like C(map()) and C(select()) to choose items in the list.
The main difference between tests and filters are that Jinja tests are used for comparisons, whereas filters are used for data manipulation, and have different applications in jinja. Tests can also be used in list processing filters, like ``map()`` and ``select()`` to choose items in the list.
Like all templating, tests always execute on the Ansible controller, **not** on the target of a task, as they test local data.