From 64dcc7def0298290a87f7aecafcd6eef356318ae Mon Sep 17 00:00:00 2001 From: Alicia Cozine Date: Thu, 19 Apr 2018 19:02:48 -0500 Subject: [PATCH] Fixes more rST errors (#39042) * removes include, avoids duplicate label rST warnings * reduces literal_block errors on playbooks_filters * addresses TOC errors * ref error on modules page * trying ref for list_of_database_modules --- .../rst/dev_guide/developing_modules.rst | 2 - .../developing_modules_in_groups.rst | 2 +- docs/docsite/rst/index.rst | 2 +- docs/docsite/rst/plugins/plugins.rst | 4 +- docs/docsite/rst/user_guide/intro.rst | 4 +- docs/docsite/rst/user_guide/modules.rst | 2 +- .../rst/user_guide/playbooks_filters.rst | 184 ++++++++++-------- 7 files changed, 107 insertions(+), 93 deletions(-) diff --git a/docs/docsite/rst/dev_guide/developing_modules.rst b/docs/docsite/rst/dev_guide/developing_modules.rst index ebcff48a6c..7dbe227e63 100644 --- a/docs/docsite/rst/dev_guide/developing_modules.rst +++ b/docs/docsite/rst/dev_guide/developing_modules.rst @@ -108,5 +108,3 @@ The following topics will discuss how to develop and work with modules: `irc.freenode.net `_ #ansible IRC chat channel - -.. include:: ./developing_module_utilities.rst diff --git a/docs/docsite/rst/dev_guide/developing_modules_in_groups.rst b/docs/docsite/rst/dev_guide/developing_modules_in_groups.rst index 645fd83d82..9cc70c446d 100644 --- a/docs/docsite/rst/dev_guide/developing_modules_in_groups.rst +++ b/docs/docsite/rst/dev_guide/developing_modules_in_groups.rst @@ -33,7 +33,7 @@ Although it's tempting to get straight into coding, there are a few things to be Naming Convention ````````````````` -As you may have noticed when looking under ``lib/ansible/modules/`` we support up to two directories deep (but no deeper), e.g. `databases/mysql`. This is used to group files on disk as well as group related modules into categories and topics the Module Index, for example: :doc:`../list_of_database_modules`. +As you may have noticed when looking under ``lib/ansible/modules/`` we support up to two directories deep (but no deeper), e.g. `databases/mysql`. This is used to group files on disk as well as group related modules into categories and topics the Module Index, for example: :ref:`list_of_database_modules`. The directory name should represent the *product* or *OS* name, not the company name. diff --git a/docs/docsite/rst/index.rst b/docs/docsite/rst/index.rst index efcb7f939c..e8a57c1a7b 100644 --- a/docs/docsite/rst/index.rst +++ b/docs/docsite/rst/index.rst @@ -66,7 +66,7 @@ Ansible releases a new major release of Ansible approximately every two months. :caption: Ansible for Network Automation network/index - network/getting_started + network/getting_started/index .. toctree:: :maxdepth: 2 diff --git a/docs/docsite/rst/plugins/plugins.rst b/docs/docsite/rst/plugins/plugins.rst index 4ec3de1e15..4ecbcdb4ed 100644 --- a/docs/docsite/rst/plugins/plugins.rst +++ b/docs/docsite/rst/plugins/plugins.rst @@ -22,8 +22,8 @@ This section covers the various types of plugins that are included with Ansible: shell strategy vars - playbooks_filters - playbooks_tests + ../user_guide/playbooks_filters + ../user_guide/playbooks_tests ../user_guide/plugin_filtering_config .. seealso:: diff --git a/docs/docsite/rst/user_guide/intro.rst b/docs/docsite/rst/user_guide/intro.rst index 4e9e81c1d8..bb0e531567 100644 --- a/docs/docsite/rst/user_guide/intro.rst +++ b/docs/docsite/rst/user_guide/intro.rst @@ -6,13 +6,13 @@ Before we start exploring the main components of Ansible -- playbooks, configura .. toctree:: :maxdepth: 1 - installation_guide/index + ../installation_guide/index ../dev_guide/overview_architecture intro_getting_started intro_inventory intro_dynamic_inventory intro_patterns intro_adhoc - intro_configuration + ../installation_guide/intro_configuration intro_bsd intro_windows diff --git a/docs/docsite/rst/user_guide/modules.rst b/docs/docsite/rst/user_guide/modules.rst index 88587d6ab0..558b224819 100644 --- a/docs/docsite/rst/user_guide/modules.rst +++ b/docs/docsite/rst/user_guide/modules.rst @@ -7,7 +7,7 @@ Working With Modules :maxdepth: 1 modules_intro - common_return_values + ../reference_appendices/common_return_values modules_support ../modules/modules_by_category diff --git a/docs/docsite/rst/user_guide/playbooks_filters.rst b/docs/docsite/rst/user_guide/playbooks_filters.rst index 5831d8a270..0700d32e00 100644 --- a/docs/docsite/rst/user_guide/playbooks_filters.rst +++ b/docs/docsite/rst/user_guide/playbooks_filters.rst @@ -384,74 +384,85 @@ Network CLI filters To convert the output of a network device CLI command into structured JSON output, use the ``parse_cli`` filter:: +.. code-block:: yaml + {{ output | parse_cli('path/to/spec') }} + The ``parse_cli`` filter will load the spec file and pass the command output through it, returning JSON output. The YAML spec file defines how to parse the CLI output. The spec file should be valid formatted YAML. It defines how to parse the CLI output and return JSON data. Below is an example of a valid spec file that -will parse the output from the ``show vlan`` command.:: +will parse the output from the ``show vlan`` command. - --- - vars: - vlan: - vlan_id: "{{ item.vlan_id }}" - name: "{{ item.name }}" - enabled: "{{ item.state != 'act/lshut' }}" - state: "{{ item.state }}" +.. code-block:: yaml + + --- + vars: + vlan: + vlan_id: "{{ item.vlan_id }}" + name: "{{ item.name }}" + enabled: "{{ item.state != 'act/lshut' }}" + state: "{{ item.state }}" + + keys: + vlans: + value: "{{ vlan }}" + items: "^(?P\\d+)\\s+(?P\\w+)\\s+(?Pactive|act/lshut|suspended)" + state_static: + value: present - keys: - vlans: - value: "{{ vlan }}" - items: "^(?P\\d+)\\s+(?P\\w+)\\s+(?Pactive|act/lshut|suspended)" - state_static: - value: present The spec file above will return a JSON data structure that is a list of hashes with the parsed VLAN information. The same command could be parsed into a hash by using the key and values directives. Here is an example of how to parse the output into a hash -value using the same ``show vlan`` command.:: +value using the same ``show vlan`` command. - --- - vars: - vlan: - key: "{{ item.vlan_id }}" - values: - vlan_id: "{{ item.vlan_id }}" - name: "{{ item.name }}" - enabled: "{{ item.state != 'act/lshut' }}" - state: "{{ item.state }}" +.. code-block:: yaml + + --- + vars: + vlan: + key: "{{ item.vlan_id }}" + values: + vlan_id: "{{ item.vlan_id }}" + name: "{{ item.name }}" + enabled: "{{ item.state != 'act/lshut' }}" + state: "{{ item.state }}" + + keys: + vlans: + value: "{{ vlan }}" + items: "^(?P\\d+)\\s+(?P\\w+)\\s+(?Pactive|act/lshut|suspended)" + state_static: + value: present - keys: - vlans: - value: "{{ vlan }}" - items: "^(?P\\d+)\\s+(?P\\w+)\\s+(?Pactive|act/lshut|suspended)" - state_static: - value: present Another common use case for parsing CLI commands is to break a large command into blocks that can be parsed. This can be done using the ``start_block`` and -``end_block`` directives to break the command into blocks that can be parsed.:: +``end_block`` directives to break the command into blocks that can be parsed. - --- - vars: - interface: - name: "{{ item[0].match[0] }}" - state: "{{ item[1].state }}" - mode: "{{ item[2].match[0] }}" +.. code-block:: yaml - keys: - interfaces: - value: "{{ interface }}" - start_block: "^Ethernet.*$" - end_block: "^$" - items: - - "^(?PEthernet\\d\\/\\d*)" - - "admin state is (?P.+)," - - "Port mode is (.+)" + --- + vars: + interface: + name: "{{ item[0].match[0] }}" + state: "{{ item[1].state }}" + mode: "{{ item[2].match[0] }}" + + keys: + interfaces: + value: "{{ interface }}" + start_block: "^Ethernet.*$" + end_block: "^$" + items: + - "^(?PEthernet\\d\\/\\d*)" + - "admin state is (?P.+)," + - "Port mode is (.+)" The example above will parse the output of ``show interface`` into a list of @@ -482,54 +493,59 @@ The spec file should be valid formatted YAML. It defines how to parse the XML output and return JSON data. Below is an example of a valid spec file that -will parse the output from the ``show vlan | display xml`` command.:: +will parse the output from the ``show vlan | display xml`` command. - --- - vars: - vlan: - vlan_id: "{{ item.vlan_id }}" - name: "{{ item.name }}" - desc: "{{ item.desc }}" - enabled: "{{ item.state.get('inactive') != 'inactive' }}" - state: "{% if item.state.get('inactive') == 'inactive'%} inactive {% else %} active {% endif %}" +.. code-block:: yaml + + --- + vars: + vlan: + vlan_id: "{{ item.vlan_id }}" + name: "{{ item.name }}" + desc: "{{ item.desc }}" + enabled: "{{ item.state.get('inactive') != 'inactive' }}" + state: "{% if item.state.get('inactive') == 'inactive'%} inactive {% else %} active {% endif %}" + + keys: + vlans: + value: "{{ vlan }}" + top: configuration/vlans/vlan + items: + vlan_id: vlan-id + name: name + desc: description + state: ".[@inactive='inactive']" - keys: - vlans: - value: "{{ vlan }}" - top: configuration/vlans/vlan - items: - vlan_id: vlan-id - name: name - desc: description - state: ".[@inactive='inactive']" The spec file above will return a JSON data structure that is a list of hashes with the parsed VLAN information. The same command could be parsed into a hash by using the key and values directives. Here is an example of how to parse the output into a hash -value using the same ``show vlan | display xml`` command.:: +value using the same ``show vlan | display xml`` command. - --- - vars: - vlan: - key: "{{ item.vlan_id }}" - values: - vlan_id: "{{ item.vlan_id }}" - name: "{{ item.name }}" - desc: "{{ item.desc }}" - enabled: "{{ item.state.get('inactive') != 'inactive' }}" - state: "{% if item.state.get('inactive') == 'inactive'%} inactive {% else %} active {% endif %}" +.. code-block:: yaml - keys: - vlans: - value: "{{ vlan }}" - top: configuration/vlans/vlan - items: - vlan_id: vlan-id - name: name - desc: description - state: ".[@inactive='inactive']" + --- + vars: + vlan: + key: "{{ item.vlan_id }}" + values: + vlan_id: "{{ item.vlan_id }}" + name: "{{ item.name }}" + desc: "{{ item.desc }}" + enabled: "{{ item.state.get('inactive') != 'inactive' }}" + state: "{% if item.state.get('inactive') == 'inactive'%} inactive {% else %} active {% endif %}" + + keys: + vlans: + value: "{{ vlan }}" + top: configuration/vlans/vlan + items: + vlan_id: vlan-id + name: name + desc: description + state: ".[@inactive='inactive']" The value of ``top`` is the XPath relative to the XML root node.