Skip to content

Fix YAML syntax, adjust more code block languages #2408

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Feb 14, 2025
Merged

Fix YAML syntax, adjust more code block languages #2408

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
f5b3b38
Fix broken YAML, or adjust code block type.
felixfontein Feb 12, 2025
8ee7622
Normalize code block type.
felixfontein Feb 12, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion docs/docsite/rst/collections_guide/collections_using_playbooks.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -34,7 +34,7 @@ This works for roles or any type of plugin distributed within the collection:

- name: Call a debug task
ansible.builtin.debug:
msg: '{{ lookup("my_namespace.my_collection.lookup1", 'param1')| my_namespace.my_collection.filter1 }}'
msg: '{{ lookup("my_namespace.my_collection.lookup1", "param1") | my_namespace.my_collection.filter1 }}'

Simplifying module names with the ``collections`` keyword
---------------------------------------------------------
Expand Down
6 changes: 3 additions & 3 deletions docs/docsite/rst/dev_guide/developing_collections_creating.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -90,12 +90,12 @@ A collection skeleton is a directory that looks like a collection directory but

An example ``galaxy.yml.j2`` file that accepts an optional dictionary variable ``dependencies`` could look like this:

.. code-block:: yaml+jinja
.. code-block:: jinja

namespace: {{ namespace }}
name: {{ collection_name }}
version: "{{ (version|quote) is version("0.0.0", operator="gt", version_type="semver")|ternary(version, undef("version must be a valid semantic version greater than 0.0.0")) }}"
dependencies: {{ dependencies|default({}, true) }}
version: {{ (version|quote) is version('0.0.0', operator='gt', version_type='semver')|ternary(version, undef('version must be a valid semantic version greater than 0.0.0')) }}
dependencies: {{ dependencies | default({}, true) }}

To initialize a collection using the new template, pass the path to the skeleton with ``ansible-galaxy collection init``:

Expand Down
2 changes: 1 addition & 1 deletion docs/docsite/rst/dev_guide/migrating_roles.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -71,7 +71,7 @@ You will need to use the Fully Qualified Collection Name (FQCN) to use the roles

So for example, in the above collection, the FQCN to access ``role1`` would be:

.. code-block:: Python
.. code-block:: python

mynamespace.mycollection.role1

Expand Down
4 changes: 2 additions & 2 deletions docs/docsite/rst/dev_guide/style_guide/index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -387,7 +387,7 @@ Ensure all icons, images, diagrams, and non text elements have a meaningful alte

To add alt text in rst:

.. code-block:: reStructuredText
.. code-block:: rst

.. image:: path/networkdiag.png
:width: 400
Expand Down Expand Up @@ -416,7 +416,7 @@ Label tables with a descriptive title.

For RST:

.. code-block:: reStructuredText
.. code-block:: rst

.. table:: File descriptions

Expand Down
2 changes: 1 addition & 1 deletion docs/docsite/rst/inventory/implicit_localhost.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@ In a case like this (or ``local_action``) when Ansible needs to contact a 'local

.. code-block:: yaml

...
# ...

hosts:
localhost:
Expand Down
3 changes: 2 additions & 1 deletion docs/docsite/rst/inventory_guide/connection_details.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -27,7 +27,8 @@ By default, Ansible connects to all remote devices with the username you are usi

tasks:
- name: thing to do first in this playbook
. . .

# ...

as a host variable in inventory:

Expand Down
6 changes: 3 additions & 3 deletions docs/docsite/rst/network/dev_guide/developing_resource_modules_network.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -139,7 +139,7 @@ For example, the resource model builder includes the ``myos_interfaces.yml`` sam
short_description: 'Manages <xxxx> attributes of <network_os> <resource>'
description: 'Manages <xxxx> attributes of <network_os> <resource>.'
author: Ansible Network Engineer
notes:
notes:
- 'Tested against <network_os> <version>'
options:
config:
Expand Down Expand Up @@ -361,7 +361,7 @@ This example shows how to use the generated collection in a playbook:

.. code-block:: yaml

----
---
- hosts: myos101
gather_facts: False
tasks:
Expand Down Expand Up @@ -616,7 +616,7 @@ The following example walks through the integration tests for the ``vyos.vyos.vy
that:
- "{{ overridden['after'] | symmetric_difference(result['before'])
| length == 0 }}"
always:
always:
- import_tasks: _remove_config.yaml


Expand Down
6 changes: 3 additions & 3 deletions docs/docsite/rst/network/getting_started/first_inventory.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -361,7 +361,7 @@ and type in the vault password for ``my_user``.

The :option:`--vault-id <ansible-playbook --vault-id>` flag allows different vault passwords for different users or different levels of access. The output includes the username ``my_user`` from your ``ansible-vault`` command and uses the YAML syntax ``key: value``:

.. code-block:: yaml
.. code-block:: text
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
.. code-block:: text
.. code-block:: console

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hmm. I thought this might be console but now I'm not so sure looking at some of the changes you have below. Given this represents sample output console would make sense, wouldn't it?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@felixfontein The code-blocks preceding this one are console. Looking at it again, I still think there is a case for console over text. Looking at the pygment docs for the lexer: https://pygments.org/docs/lexers/#pygments.lexers.shell.BashSessionLexer

This code block, while not showing a direct command like the previous ansible-vault examples, is intended to show the output of the --vault-id flag and is in the context of a shell session.

I'm probably being waaaay too pedantic about it though. I don't feel super strongly but am not convinced text is better than console.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think console only really makes sense if there's also a prompt involved. The lexer is for formatting prompts, commands, and output differently. Here you can just see program output.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

TBH some of the other ones I've tagged as 'console' likely aren't really console either.

I'm going to keep this one and the others as-is for now, maybe at some point someone has to take a closer look at all these at once. At least now all code blocks are tagged with a language, so they're easier to find :)


ansible_password: !vault |
$ANSIBLE_VAULT;1.2;AES256;my_user
Expand All @@ -376,7 +376,7 @@ This is an example using an extract from a YAML inventory, as the INI format do

.. code-block:: yaml

...
# ...

vyos: # this is a group in yaml inventory, but you can also do under a host
vars:
Expand All @@ -391,7 +391,7 @@ This is an example using an extract from a YAML inventory, as the INI format do
3837646266663835640a313164343535316666653031353763613037656362613535633538386539
65656439626166666363323435613131643066353762333232326232323565376635

...
# ...

To use an inline vaulted variables with an INI inventory you need to store it in a 'vars' file in YAML format,
it can reside in host_vars/ or group_vars/ to be automatically picked up or referenced from a play through ``vars_files`` or ``include_vars``.
Expand Down
16 changes: 8 additions & 8 deletions docs/docsite/rst/network/user_guide/cli_parsing.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -177,7 +177,7 @@ Lastly in this task, the ``set_fact`` option sets the following ``interfaces`` f
Ethernet1/10:
hardware: 100/1000/10000 Ethernet
mac_address: 5254.005a.f8c6
<...>
# ...


Linux example
Expand Down Expand Up @@ -278,7 +278,7 @@ Lastly in this task, the ``set_fact`` option sets the following ``interfaces`` f
name: enp64s0u1
state: up
up: true
<...>
# ...


Parsing JSON
Expand Down Expand Up @@ -429,7 +429,7 @@ This task sets the following fact as the ``interfaces`` fact for the host:
ip: 192.168.101.14
prefix_length: '24'
link_state: up
<...>
# ...


Parsing with textfsm
Expand Down Expand Up @@ -616,11 +616,11 @@ This example task runs the ``show interface`` command and parses the output as X
.. code-block:: yaml

- name: "Run command and parse as xml"
ansible.utils.cli_parse:
command: show interface | xml
parser:
name: ansible.utils.xml
set_fact: interfaces
ansible.utils.cli_parse:
command: show interface | xml
parser:
name: ansible.utils.xml
register: interfaces

.. note::

Expand Down
2 changes: 1 addition & 1 deletion docs/docsite/rst/network/user_guide/network_debug_troubleshooting.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -56,7 +56,7 @@ Before running ``ansible-playbook``, run the following commands to enable loggin

After Ansible has finished running you can inspect the log file which has been created on the Ansible control node:

.. code::
.. code:: console

less $ANSIBLE_LOG_PATH

Expand Down
8 changes: 4 additions & 4 deletions docs/docsite/rst/network/user_guide/network_resource_modules.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -57,9 +57,9 @@ The following table shows an example of how an initial resource configuration ch
| | | .. code-block:: text |
| interface loopback100 | config: | |
| ip address 10.10.1.100 255.255.255.0 | - ipv6: | interface loopback100 |
| ipv6 address FC00:100/64 | - address: fc00::100/64 | ip address 10.10.1.100 255.255.255.0|
| | - address: fc00::101/64 | ipv6 address FC00:100/64 |
| | name: loopback100 | ipv6 address FC00:101/64 |
| ipv6 address FC00:100/64 | - address: fc00::100/64 | ip address 10.10.1.100 255.255.255.0|
| | - address: fc00::101/64 | ipv6 address FC00:100/64 |
| | name: loopback100 | ipv6 address FC00:101/64 |
| | +-----------------------------------------+
| | | *replaced* |
| | | .. code-block:: text |
Expand Down Expand Up @@ -88,7 +88,7 @@ Network resource modules return the following details:
* The *after* state - the new resource configuration that exists on the network device after the task was executed.
* Commands - any commands configured on the device.

.. code-block:: yaml
.. code-block:: console

ok: [nxos101] =>
result:
Expand Down
4 changes: 2 additions & 2 deletions docs/docsite/rst/network/user_guide/platform_ce.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -46,7 +46,7 @@ Using CLI in Ansible
Example CLI inventory ``[ce:vars]``
--------------------------------------

.. code-block:: yaml
.. code-block:: ini

[ce:vars]
ansible_connection=ansible.netcommon.network_cli
Expand Down Expand Up @@ -98,7 +98,7 @@ Once NETCONF is enabled, change your variables to use the NETCONF connection.
Example NETCONF inventory ``[ce:vars]``
------------------------------------------

.. code-block:: yaml
.. code-block:: ini

[ce:vars]
ansible_connection=ansible.netcommon.netconf
Expand Down
4 changes: 2 additions & 2 deletions docs/docsite/rst/network/user_guide/platform_iosxr.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -49,7 +49,7 @@ Using CLI in Ansible
Example CLI inventory ``[iosxr:vars]``
--------------------------------------

.. code-block:: yaml
.. code-block:: ini

[iosxr:vars]
ansible_connection=ansible.netcommon.network_cli
Expand Down Expand Up @@ -99,7 +99,7 @@ Once NETCONF is enabled, change your variables to use the NETCONF connection.
Example NETCONF inventory ``[iosxr:vars]``
------------------------------------------

.. code-block:: yaml
.. code-block:: ini

[iosxr:vars]
ansible_connection=ansible.netcommon.netconf
Expand Down
4 changes: 2 additions & 2 deletions docs/docsite/rst/network/user_guide/platform_junos.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -50,7 +50,7 @@ Using CLI in Ansible
Example CLI inventory ``[junos:vars]``
--------------------------------------

.. code-block:: yaml
.. code-block:: ini

[junos:vars]
ansible_connection=ansible.netcommon.network_cli
Expand Down Expand Up @@ -100,7 +100,7 @@ Once NETCONF is enabled, change your variables to use the NETCONF connection.
Example NETCONF inventory ``[junos:vars]``
------------------------------------------

.. code-block:: yaml
.. code-block:: ini

[junos:vars]
ansible_connection=ansible.netcommon.netconf
Expand Down
2 changes: 1 addition & 1 deletion docs/docsite/rst/network/user_guide/platform_netconf_enabled.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -60,7 +60,7 @@ Once NETCONF is enabled, change your variables to use the NETCONF connection.
Example NETCONF inventory ``[junos:vars]``
------------------------------------------

.. code-block:: yaml
.. code-block:: ini

[junos:vars]
ansible_connection=ansible.netcommon.netconf
Expand Down
2 changes: 1 addition & 1 deletion docs/docsite/rst/os_guide/intro_bsd.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -138,7 +138,7 @@ The playbook below

.. code-block:: yaml+jinja

shell> cat playbook.yml
# playbook.yml
- hosts: test_11
gather_facts: false
tasks:
Expand Down
2 changes: 1 addition & 1 deletion docs/docsite/rst/os_guide/windows_usage.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -300,7 +300,7 @@ rules apply:

With those rules in mind, here are some examples of quoting:

.. code-block:: yaml+jinja
.. code-block:: console

- win_command: C:\temp\executable.exe argument1 "argument 2" "C:\path\with space" "double \"quoted\""

Expand Down
4 changes: 2 additions & 2 deletions docs/docsite/rst/playbook_guide/playbooks_advanced_syntax.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -55,7 +55,7 @@ You define an anchor with ``&``, then refer to it using an alias, denoted with `
.. code-block:: yaml

---
...
# ...
vars:
app1:
jvm: &jvm_opts
Expand All @@ -66,7 +66,7 @@ You define an anchor with ``&``, then refer to it using an alias, denoted with `
jvm:
<<: *jvm_opts
path: /usr/lib/app2
...
# ...

Here, ``app1`` and ``app2`` share the values for ``opts`` and ``port`` using the anchor ``&jvm_opts`` and the alias ``*jvm_opts``.
The value for ``path`` is merged by ``<<`` or `merge operator <https://yaml.org/type/merge.html>`_.
Expand Down
2 changes: 1 addition & 1 deletion docs/docsite/rst/playbook_guide/playbooks_debugger.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -93,7 +93,7 @@ You can enable the task debugger globally with a setting in ``ansible.cfg`` or w

To enable the task debugger from ``ansible.cfg``, add this setting to the ``[defaults]`` section:

.. code-block:: yaml
.. code-block:: ini

[defaults]
enable_task_debugger = True
Expand Down
Loading