From 1718db1af7d4063c99eeaee4b9a83e18a73a42ed Mon Sep 17 00:00:00 2001 From: Ganesh Hubale Date: Sat, 11 Jan 2025 12:46:26 +0530 Subject: [PATCH 1/3] Unpin rstcheck dependency and update to version 6.x - Removed the version pin(5.0.0) for rstcheck to allow updates to the latest version (6.x). - Updated the rstcheck.py script to handle changes in the rstcheck-core API and output format. Signed-off-by: Ganesh Hubale --- tests/checkers/rstcheck.py | 79 ++++++++++++-------------------------- tests/constraints-base.in | 2 +- tests/requirements.txt | 2 +- 3 files changed, 27 insertions(+), 56 deletions(-) diff --git a/tests/checkers/rstcheck.py b/tests/checkers/rstcheck.py index b20dc6e5746..4391dde9e2e 100644 --- a/tests/checkers/rstcheck.py +++ b/tests/checkers/rstcheck.py @@ -1,63 +1,34 @@ -"""Sanity test using rstcheck and sphinx.""" -from __future__ import annotations - -import re -import subprocess +from rstcheck_core.runner import RstcheckMainRunner +from rstcheck_core.config import RstcheckConfig +import pathlib import sys - def main(): - paths = sys.argv[1:] or sys.stdin.read().splitlines() - - encoding = 'utf-8' - - ignore_substitutions = ( - 'br', + # Define the paths to check (passed as CLI arguments or from stdin) + paths = [pathlib.Path(p) for p in (sys.argv[1:] or sys.stdin.read().splitlines())] + + # Define the configuration for rstcheck + config = RstcheckConfig( + ignore_roles=[ + "ansplugin", "ansopt", "ansretval", "ansval", "ansenvvar", "ansenvvarref" + ], + ignore_substitutions=["br"], + report_level="warning", # Adjust report level as needed -> ["info": 1, "warning": 2, "error": 3,"severe": 4, "none": 5,] + recursive=True, # Set to True to check directories recursively ) - cmd = [ - sys.executable, - '-c', 'import rstcheck; rstcheck.main();', - '--report', 'warning', - '--ignore-roles', 'ansplugin,ansopt,ansretval,ansval,ansenvvar,ansenvvarref', - '--ignore-substitutions', ','.join(ignore_substitutions), - ] + paths - - process = subprocess.run(cmd, - stdin=subprocess.DEVNULL, - stdout=subprocess.PIPE, - stderr=subprocess.PIPE, - check=False, - ) - - if process.stdout: - raise Exception(process.stdout) - - pattern = re.compile(r'^(?P[^:]*):(?P[0-9]+): \((?PINFO|WARNING|ERROR|SEVERE)/[0-4]\) (?P.*)$') - - results = parse_to_list_of_dict(pattern, process.stderr.decode(encoding)) - - for result in results: - print('%s:%s:%s: %s' % (result['path'], result['line'], 0, result['message'])) - - -def parse_to_list_of_dict(pattern, value): - matched = [] - unmatched = [] - - for line in value.splitlines(): - match = re.search(pattern, line) - - if match: - matched.append(match.groupdict()) - else: - unmatched.append(line) - - if unmatched: - raise Exception('Pattern "%s" did not match values:\n%s' % (pattern, '\n'.join(unmatched))) + # Initialize the runner + runner = RstcheckMainRunner( + check_paths=paths, + rstcheck_config=config, + overwrite_config=True, + ) - return matched + # Run the checks + exit_code = runner.run() + # Exit with the appropriate code + sys.exit(exit_code) -if __name__ == '__main__': +if __name__ == "__main__": main() diff --git a/tests/constraints-base.in b/tests/constraints-base.in index 1928c3a06d1..b4411764c9e 100644 --- a/tests/constraints-base.in +++ b/tests/constraints-base.in @@ -1,4 +1,4 @@ # Known limitations for indirect/transitive dependencies. -rstcheck < 6 # rstcheck 6.x has problem with rstcheck.core triggered by include files w/ sphinx directives https://github.com/rstcheck/rstcheck-core/issues/3 +rstcheck>=6.2.4 sphinx-rtd-theme>=2.0.0 # Fix 404 pages with new sphinx -- https://github.com/ansible/ansible-documentation/issues/678 diff --git a/tests/requirements.txt b/tests/requirements.txt index 7c6d8121051..916a943dee5 100644 --- a/tests/requirements.txt +++ b/tests/requirements.txt @@ -121,7 +121,7 @@ requests==2.32.3 # via sphinx resolvelib==1.0.1 # via -r tests/requirements-relaxed.in -rstcheck==5.0.0 +rstcheck>=6.2.4 # via # -c tests/constraints-base.in # -r tests/requirements-relaxed.in From 3351d0c73beeacf7566195f45139624c8e5db744 Mon Sep 17 00:00:00 2001 From: Ganesh Hubale Date: Sat, 11 Jan 2025 22:51:32 +0530 Subject: [PATCH 2/3] Fix RST syntax and resolve rstcheck validation errors - Corrected YAML formatting issues, ensuring valid syntax for rstcheck validation. - Fixed malformed tables by aligning columns and ensuring consistent formatting. - Addressed unreferenced and duplicate hyperlink targets, ensuring proper references or removal of unused targets. - Adjusted invalid code block types (e.g., switching from yaml to ini or text) for compatibility with rstcheck. - Resolved custom role (ansplugin) issues by either ignoring the role. Signed-off-by: Ganesh Hubale --- .../rst/collections_guide/collections_using_playbooks.rst | 2 +- .../rst/dev_guide/developing_collections_creating.rst | 2 +- docs/docsite/rst/inventory/implicit_localhost.rst | 2 +- docs/docsite/rst/inventory_guide/intro_patterns.rst | 4 ++-- .../dev_guide/developing_resource_modules_network.rst | 6 +++--- .../rst/network/getting_started/first_inventory.rst | 4 ++-- docs/docsite/rst/network/user_guide/cli_parsing.rst | 8 ++++---- .../rst/network/user_guide/network_best_practices_2.5.rst | 2 +- .../rst/network/user_guide/network_resource_modules.rst | 4 ++-- docs/docsite/rst/os_guide/intro_bsd.rst | 2 +- .../rst/playbook_guide/playbooks_advanced_syntax.rst | 8 ++++---- docs/docsite/rst/playbook_guide/playbooks_debugger.rst | 6 ++++-- docs/docsite/rst/playbook_guide/playbooks_tags.rst | 6 +++--- docs/docsite/rst/playbook_guide/playbooks_tests.rst | 2 +- docs/docsite/rst/plugins/vars.rst | 2 +- docs/docsite/rst/porting_guides/porting_guide_2.0.rst | 2 +- docs/docsite/rst/reference_appendices/faq.rst | 2 +- docs/docsite/rst/tips_tricks/ansible_tips_tricks.rst | 2 +- docs/docsite/rst/vault_guide/vault_encrypting_content.rst | 6 +++--- docs/docsite/rst/vault_guide/vault_managing_passwords.rst | 2 +- 20 files changed, 38 insertions(+), 36 deletions(-) diff --git a/docs/docsite/rst/collections_guide/collections_using_playbooks.rst b/docs/docsite/rst/collections_guide/collections_using_playbooks.rst index 22f17477ece..5d3d2750eb5 100644 --- a/docs/docsite/rst/collections_guide/collections_using_playbooks.rst +++ b/docs/docsite/rst/collections_guide/collections_using_playbooks.rst @@ -18,7 +18,7 @@ Once installed, you can reference a collection content by its fully qualified co This works for roles or any type of plugin distributed within the collection: -.. code-block:: yaml +.. code-block:: ini - name: Reference collections contents using their FQCNs hosts: all diff --git a/docs/docsite/rst/dev_guide/developing_collections_creating.rst b/docs/docsite/rst/dev_guide/developing_collections_creating.rst index af44d273696..91f4dc2980f 100644 --- a/docs/docsite/rst/dev_guide/developing_collections_creating.rst +++ b/docs/docsite/rst/dev_guide/developing_collections_creating.rst @@ -90,7 +90,7 @@ 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 +.. code-block:: ini namespace: {{ namespace }} name: {{ collection_name }} diff --git a/docs/docsite/rst/inventory/implicit_localhost.rst b/docs/docsite/rst/inventory/implicit_localhost.rst index a242a8c07ef..e3b570fdc18 100644 --- a/docs/docsite/rst/inventory/implicit_localhost.rst +++ b/docs/docsite/rst/inventory/implicit_localhost.rst @@ -17,7 +17,7 @@ When you try to reference a ``localhost`` and you don't have it defined in inven In a case like this (or ``local_action``) when Ansible needs to contact a 'localhost' but you did not supply one, we create one for you. This host is defined with specific connection variables equivalent to this in an inventory: -.. code-block:: yaml +.. code-block:: ini ... diff --git a/docs/docsite/rst/inventory_guide/intro_patterns.rst b/docs/docsite/rst/inventory_guide/intro_patterns.rst index ac75090a33f..9aa59278d74 100644 --- a/docs/docsite/rst/inventory_guide/intro_patterns.rst +++ b/docs/docsite/rst/inventory_guide/intro_patterns.rst @@ -179,7 +179,7 @@ Slicing at specific items If *i* is negative, the index is relative to the end of sequence *s*: ``len(s) + i`` is substituted. However ``-0`` is ``0``. -.. code-block:: yaml +.. code-block:: python webservers[0] # == cobweb webservers[-1] # == weber @@ -198,7 +198,7 @@ If *i* is greater than *j*, the slice is empty. If *i* is equal to *j*, the *s[i]* is substituted. -.. code-block:: yaml +.. code-block:: python webservers[0:2] # == webservers[0],webservers[1],webservers[2] # == cobweb,webbing,weber diff --git a/docs/docsite/rst/network/dev_guide/developing_resource_modules_network.rst b/docs/docsite/rst/network/dev_guide/developing_resource_modules_network.rst index 3df7870ac9f..c65f227403d 100644 --- a/docs/docsite/rst/network/dev_guide/developing_resource_modules_network.rst +++ b/docs/docsite/rst/network/dev_guide/developing_resource_modules_network.rst @@ -123,7 +123,7 @@ For any subsequent changes to the functionality, update the model first and use For example, the resource model builder includes the ``myos_interfaces.yml`` sample in the :file:`models` directory, as seen below: -.. code-block:: yaml +.. code-block:: ini --- GENERATOR_VERSION: '1.0' @@ -359,7 +359,7 @@ Using the collection This example shows how to use the generated collection in a playbook: - .. code-block:: yaml + .. code-block:: ini ---- - hosts: myos101 @@ -558,7 +558,7 @@ The following example walks through the integration tests for the ``vyos.vyos.vy ``test/integration/targets/vyos_l3_interfaces/tests/cli/overridden.yaml`` -.. code-block:: yaml +.. code-block:: ini --- - debug: diff --git a/docs/docsite/rst/network/getting_started/first_inventory.rst b/docs/docsite/rst/network/getting_started/first_inventory.rst index 48da95b7d6d..b05213c30c8 100644 --- a/docs/docsite/rst/network/getting_started/first_inventory.rst +++ b/docs/docsite/rst/network/getting_started/first_inventory.rst @@ -361,7 +361,7 @@ and type in the vault password for ``my_user``. The :option:`--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:: ini ansible_password: !vault | $ANSIBLE_VAULT;1.2;AES256;my_user @@ -374,7 +374,7 @@ The :option:`--vault-id ` flag allows different vau This is an example using an extract from a YAML inventory, as the INI format does not support inline vaults: -.. code-block:: yaml +.. code-block:: ini ... diff --git a/docs/docsite/rst/network/user_guide/cli_parsing.rst b/docs/docsite/rst/network/user_guide/cli_parsing.rst index 95e372b28be..443d1daebac 100644 --- a/docs/docsite/rst/network/user_guide/cli_parsing.rst +++ b/docs/docsite/rst/network/user_guide/cli_parsing.rst @@ -167,7 +167,7 @@ Taking a deeper dive into this task: Lastly in this task, the ``set_fact`` option sets the following ``interfaces`` fact for the device based on the now-structured data returned from ``cli_parse``: -.. code-block:: yaml +.. code-block:: ini Ethernet1/1: hardware: 100/1000/10000 Ethernet @@ -258,7 +258,7 @@ This task assumes you previously gathered facts to determine the ``ansible_distr Lastly in this task, the ``set_fact`` option sets the following ``interfaces`` fact for the host, based on the now-structured data returned from ``cli_parse``: -.. code-block:: yaml +.. code-block:: ini lo: broadcast: false @@ -399,7 +399,7 @@ Taking a deeper dive into this task: This task sets the following fact as the ``interfaces`` fact for the host: -.. code-block:: yaml +.. code-block:: ini mgmt0: admin_state: up @@ -615,7 +615,7 @@ Although Ansible contains a number of plugins that can convert XML to Ansible na This example task runs the ``show interface`` command and parses the output as XML: -.. code-block:: yaml +.. code-block:: ini - name: "Run command and parse as xml" ansible.utils.cli_parse: diff --git a/docs/docsite/rst/network/user_guide/network_best_practices_2.5.rst b/docs/docsite/rst/network/user_guide/network_best_practices_2.5.rst index 3b4854cd90e..b462542eb8d 100644 --- a/docs/docsite/rst/network/user_guide/network_best_practices_2.5.rst +++ b/docs/docsite/rst/network/user_guide/network_best_practices_2.5.rst @@ -91,7 +91,7 @@ The "Vault" feature of Ansible allows you to keep sensitive data such as passwor Here's what it would look like if you specified your SSH passwords (encrypted with Ansible Vault) among your variables: -.. code-block:: yaml +.. code-block:: ini ansible_connection: ansible.netcommon.network_cli ansible_network_os: vyos.vyos.vyos diff --git a/docs/docsite/rst/network/user_guide/network_resource_modules.rst b/docs/docsite/rst/network/user_guide/network_resource_modules.rst index fbeeaa93984..794f8964270 100644 --- a/docs/docsite/rst/network/user_guide/network_resource_modules.rst +++ b/docs/docsite/rst/network/user_guide/network_resource_modules.rst @@ -53,7 +53,7 @@ The following table shows an example of how an initial resource configuration ch +-----------------------------------------+------------------------------------+-----------------------------------------+ | Resource starting configuration | task-provided configuration (YAML) | Final resource configuration on device | +=========================================+====================================+=========================================+ -| .. code-block:: text | .. code-block:: yaml | *merged* | +| .. code-block:: text | .. code-block:: ini | *merged* | | | | .. code-block:: text | | interface loopback100 | config: | | | ip address 10.10.1.100 255.255.255.0 | - ipv6: | interface loopback100 | @@ -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:: ini ok: [nxos101] => result: diff --git a/docs/docsite/rst/os_guide/intro_bsd.rst b/docs/docsite/rst/os_guide/intro_bsd.rst index bcbeba5a227..4c09faec670 100644 --- a/docs/docsite/rst/os_guide/intro_bsd.rst +++ b/docs/docsite/rst/os_guide/intro_bsd.rst @@ -157,7 +157,7 @@ The playbook below displays the details -.. code-block:: yaml +.. code-block:: shell shell> ANSIBLE_STDOUT_CALLBACK=yaml ansible-playbook -i hosts playbook.yml diff --git a/docs/docsite/rst/playbook_guide/playbooks_advanced_syntax.rst b/docs/docsite/rst/playbook_guide/playbooks_advanced_syntax.rst index e542f1164bc..efcc1e00294 100644 --- a/docs/docsite/rst/playbook_guide/playbooks_advanced_syntax.rst +++ b/docs/docsite/rst/playbook_guide/playbooks_advanced_syntax.rst @@ -16,14 +16,14 @@ When handling values returned by lookup plugins, Ansible uses a data type called You can use the same ``unsafe`` data type in variables you define, to prevent templating errors and information disclosure. You can mark values supplied by :ref:`vars_prompts` as unsafe. You can also use ``unsafe`` in playbooks. The most common use cases include passwords that allow special characters like ``{`` or ``%``, and JSON arguments that look like templates but should not be templated. For example: -.. code-block:: yaml +.. code-block:: ini --- mypassword: !unsafe 234%234{435lkj{{lkjsdf In a playbook: -.. code-block:: yaml +.. code-block:: ini --- hosts: all @@ -34,7 +34,7 @@ In a playbook: For complex variables such as hashes or arrays, use ``!unsafe`` on the individual elements: -.. code-block:: yaml +.. code-block:: ini --- my_unsafe_array: @@ -52,7 +52,7 @@ YAML anchors and aliases: sharing variable values `YAML anchors and aliases `_ help you define, maintain, and flexibly use shared variable values. You define an anchor with ``&``, then refer to it using an alias, denoted with ``*``. Here's an example that sets three values with an anchor, uses two of those values with an alias, and overrides the third value: -.. code-block:: yaml +.. code-block:: ini --- ... diff --git a/docs/docsite/rst/playbook_guide/playbooks_debugger.rst b/docs/docsite/rst/playbook_guide/playbooks_debugger.rst index 1c4fc845d8c..326235a2d51 100644 --- a/docs/docsite/rst/playbook_guide/playbooks_debugger.rst +++ b/docs/docsite/rst/playbook_guide/playbooks_debugger.rst @@ -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 @@ -116,7 +116,9 @@ If you are running legacy playbooks or roles, you may see the debugger enabled a - hosts: test strategy: debug tasks: - ... + - name: Example task + debug: + msg: "This is a debug message" Or in ansible.cfg: diff --git a/docs/docsite/rst/playbook_guide/playbooks_tags.rst b/docs/docsite/rst/playbook_guide/playbooks_tags.rst index 89124f01057..5f7aa3a7f86 100644 --- a/docs/docsite/rst/playbook_guide/playbooks_tags.rst +++ b/docs/docsite/rst/playbook_guide/playbooks_tags.rst @@ -135,7 +135,7 @@ If you want to apply a tag to many, but not all, of the tasks in your play, use Be mindful that ``tag`` selection supersedes most other logic, including ``block`` error handling. Setting a tag on a task in a ``block`` but not in the ``rescue`` or ``always`` section will prevent those from triggering if your tags selection does not cover the tasks in those sections. -.. code-block:: yaml +.. code-block:: ini - block: - debug: msg=run with tag, but always fail @@ -157,7 +157,7 @@ Adding tags to plays If all the tasks in a play should get the same tag, you can add the tag at the level of the play. For example, if you had a play with only the NTP tasks, you could tag the entire play: -.. code-block:: yaml +.. code-block:: ini - hosts: all tags: ntp @@ -455,7 +455,7 @@ Selectively running tagged tasks in reusable files If you have a role or a tasks file with tags defined at the task or block level, you can selectively run or skip those tagged tasks in a playbook if you use a dynamic include instead of a static import. You must use the same tag on the included tasks and on the include statement itself. For example, you might create a file with some tagged and some untagged tasks: -.. code-block:: yaml +.. code-block:: ini # mixed.yml tasks: diff --git a/docs/docsite/rst/playbook_guide/playbooks_tests.rst b/docs/docsite/rst/playbook_guide/playbooks_tests.rst index 15905a06218..911801ad51b 100644 --- a/docs/docsite/rst/playbook_guide/playbooks_tests.rst +++ b/docs/docsite/rst/playbook_guide/playbooks_tests.rst @@ -78,7 +78,7 @@ Vault You can test whether a variable is an inline single vault encrypted value using the ``vault_encrypted`` test. -.. code-block:: yaml +.. code-block:: ini vars: variable: !vault | diff --git a/docs/docsite/rst/plugins/vars.rst b/docs/docsite/rst/plugins/vars.rst index 1793ba68050..771e9337ff3 100644 --- a/docs/docsite/rst/plugins/vars.rst +++ b/docs/docsite/rst/plugins/vars.rst @@ -24,7 +24,7 @@ Most vars plugins are disabled by default. To enable a vars plugin, set ``vars_p Starting in Ansible 2.10, you can use vars plugins in collections. All vars plugins in collections must be explicitly enabled and must use the fully qualified collection name in the format ``namespace.collection_name.vars_plugin_name``. -.. code-block:: yaml +.. code-block:: ini [defaults] vars_plugins_enabled = host_group_vars,namespace.collection_name.vars_plugin_name diff --git a/docs/docsite/rst/porting_guides/porting_guide_2.0.rst b/docs/docsite/rst/porting_guides/porting_guide_2.0.rst index 876ca5e27e9..6b17ebdd012 100644 --- a/docs/docsite/rst/porting_guides/porting_guide_2.0.rst +++ b/docs/docsite/rst/porting_guides/porting_guide_2.0.rst @@ -74,7 +74,7 @@ uses key=value escaping which has not changed. The other option is to check for * Syntax in 2.0.x - .. code-block:: yaml + .. code-block:: ini vars: old_message: > diff --git a/docs/docsite/rst/reference_appendices/faq.rst b/docs/docsite/rst/reference_appendices/faq.rst index 3e11695088a..3abbf69fc53 100644 --- a/docs/docsite/rst/reference_appendices/faq.rst +++ b/docs/docsite/rst/reference_appendices/faq.rst @@ -846,7 +846,7 @@ for the specific application require either specific names, multiple files or so For these cases you have to handle the validation and restoration yourself. The following is a simple example of how to do this with block/rescue and backups, which most file based modules also support: -.. code-block:: yaml +.. code-block:: ini - name: maintain config and backout if validation after change fails block: diff --git a/docs/docsite/rst/tips_tricks/ansible_tips_tricks.rst b/docs/docsite/rst/tips_tricks/ansible_tips_tricks.rst index 88746d3d8be..e228e824720 100644 --- a/docs/docsite/rst/tips_tricks/ansible_tips_tricks.rst +++ b/docs/docsite/rst/tips_tricks/ansible_tips_tricks.rst @@ -174,7 +174,7 @@ You can also add group-specific settings in group vars files. In the following example, CentOS machines get the value of '42' for `asdf` but other machines get '10'. You can also use group vars files to apply roles to systems as well as set variables. -.. code-block:: yaml +.. code-block:: ini --- # file: group_vars/all diff --git a/docs/docsite/rst/vault_guide/vault_encrypting_content.rst b/docs/docsite/rst/vault_guide/vault_encrypting_content.rst index 4ba4ef787f8..2a7fb293094 100644 --- a/docs/docsite/rst/vault_guide/vault_encrypting_content.rst +++ b/docs/docsite/rst/vault_guide/vault_encrypting_content.rst @@ -59,7 +59,7 @@ For example, to encrypt the string 'foobar' using the only password stored in 'a The command above creates this content: - .. code-block:: yaml + .. code-block:: ini the_secret: !vault | $ANSIBLE_VAULT;1.1;AES256 @@ -77,7 +77,7 @@ To encrypt the string 'foooodev', add the vault ID label 'dev' with the 'dev' va The command above creates this content: - .. code-block:: yaml + .. code-block:: ini the_dev_secret: !vault | $ANSIBLE_VAULT;1.2;AES256;dev @@ -130,7 +130,7 @@ Type the string to encrypt (for example, 'hunter2'), hit ctrl-d, and wait. The sequence above creates this output: - .. code-block:: yaml + .. code-block:: ini new_user_password: !vault | $ANSIBLE_VAULT;1.2;AES256;dev diff --git a/docs/docsite/rst/vault_guide/vault_managing_passwords.rst b/docs/docsite/rst/vault_guide/vault_managing_passwords.rst index 4a685f54639..e145238c742 100644 --- a/docs/docsite/rst/vault_guide/vault_managing_passwords.rst +++ b/docs/docsite/rst/vault_guide/vault_managing_passwords.rst @@ -28,7 +28,7 @@ If you use multiple vault passwords, you can differentiate one password from ano When you pass a vault ID as an option to the :ref:`ansible-vault` command, you add a label (a hint or nickname) to the encrypted content. This label documents which password you used to encrypt it. The encrypted variable or file includes the vault ID label in plain text in the header. The vault ID is the last element before the encrypted content. For example: - .. code-block:: yaml + .. code-block:: ini my_encrypted_var: !vault | $ANSIBLE_VAULT;1.2;AES256;dev From 5858fe2f8c8c686677c4731e8a140db6dd57ef28 Mon Sep 17 00:00:00 2001 From: Don Naro Date: Thu, 16 Jan 2025 19:31:24 +0000 Subject: [PATCH 3/3] fixing up some code-block language specifiers --- .../collections_installing.rst | 2 +- .../developing_collections_distributing.rst | 2 +- .../network_debug_troubleshooting.rst | 52 +++++++++---------- docs/docsite/rst/os_guide/windows_ssh.rst | 2 +- .../playbook_guide/playbooks_templating.rst | 8 +-- .../general_precedence.rst | 2 +- 6 files changed, 34 insertions(+), 34 deletions(-) diff --git a/docs/docsite/rst/collections_guide/collections_installing.rst b/docs/docsite/rst/collections_guide/collections_installing.rst index 7c346bbb882..3384950d491 100644 --- a/docs/docsite/rst/collections_guide/collections_installing.rst +++ b/docs/docsite/rst/collections_guide/collections_installing.rst @@ -185,7 +185,7 @@ Using locally installed collections adjacent to playbooks has some benefits, suc Here is an example of keeping a collection adjacent to the current playbook, under a ``collections/ansible_collections/`` directory structure. -.. code-block:: text +.. code-block:: console ./ ├── play.yml diff --git a/docs/docsite/rst/dev_guide/developing_collections_distributing.rst b/docs/docsite/rst/dev_guide/developing_collections_distributing.rst index 9f9a8d38164..d1c3663b2cb 100644 --- a/docs/docsite/rst/dev_guide/developing_collections_distributing.rst +++ b/docs/docsite/rst/dev_guide/developing_collections_distributing.rst @@ -220,7 +220,7 @@ For example, to exclude the :file:`sensitive` folder within the ``playbooks`` fo By default, the ``MANIFEST.in`` style directives would exclude all files by default, but there are default directives in place. Those default directives are described below. To see the directives in use during build, pass ``-vvv`` with the ``ansible-galaxy collection build`` command. -.. code-block:: +.. code-block:: manifest include meta/*.yml include *.txt *.md *.rst COPYING LICENSE diff --git a/docs/docsite/rst/network/user_guide/network_debug_troubleshooting.rst b/docs/docsite/rst/network/user_guide/network_debug_troubleshooting.rst index 30668dff309..8816fc47d23 100644 --- a/docs/docsite/rst/network/user_guide/network_debug_troubleshooting.rst +++ b/docs/docsite/rst/network/user_guide/network_debug_troubleshooting.rst @@ -113,7 +113,7 @@ Be sure to fully understand the security implications of enabling this option. T Before running ``ansible-playbook`` run the following commands to enable logging: -.. code-block:: text +.. code-block:: shell # Specify the location for the log file export ANSIBLE_LOG_PATH=~/ansible.log @@ -140,7 +140,7 @@ To make this a global setting, add the following to your ``ansible.cfg`` file: or enable the environment variable `ANSIBLE_PERSISTENT_LOG_MESSAGES`: -.. code-block:: text +.. code-block:: shell # Enable device interaction logging export ANSIBLE_PERSISTENT_LOG_MESSAGES=True @@ -168,9 +168,9 @@ For Ansible this can be done by ensuring you are only running against one remote `ad hoc` refers to running Ansible to perform some quick command using ``/usr/bin/ansible``, rather than the orchestration language, which is ``/usr/bin/ansible-playbook``. In this case we can ensure connectivity by attempting to execute a single command on the remote device: -.. code-block:: text +.. code-block:: shell - ansible -m arista.eos.eos_command -a 'commands=?' -i inventory switch1.example.net -e 'ansible_connection=ansible.netcommon.network_cli' -u admin -k + ansible -m arista.eos.eos_command -a 'commands=?' -i inventory switch1.example.net -e 'ansible_connection=ansible.netcommon.network_cli' -u admin -k In the above example, we: @@ -184,7 +184,7 @@ If you have SSH keys configured correctly, you don't need to specify the ``-k`` If the connection still fails you can combine it with the enable_network_logging parameter. For example: -.. code-block:: text +.. code-block:: shell # Specify the location for the log file export ANSIBLE_LOG_PATH=~/ansible.log @@ -208,7 +208,7 @@ The ``Socket path does not exist or cannot be found`` and ``Unable to connect t For example: -.. code-block:: none +.. code-block:: json fatal: [spine02]: FAILED! => { "changed": false, @@ -221,7 +221,7 @@ For example: or -.. code-block:: none +.. code-block:: json fatal: [spine02]: FAILED! => { "changed": false, @@ -240,13 +240,13 @@ Suggestions to resolve: If the identified error message from the log file is: -.. code-block:: yaml +.. code-block:: text 2017-04-04 12:19:05,670 p=18591 u=fred | command timeout triggered, timeout value is 30 secs or -.. code-block:: yaml +.. code-block:: text 2017-04-04 12:19:05,670 p=18591 u=fred | persistent connection idle timeout triggered, timeout value is 30 secs @@ -267,7 +267,7 @@ The ``unable to open shell`` message means that the ``ansible-connection`` daemo For example: -.. code-block:: none +.. code-block:: console TASK [prepare_eos_tests : enable cli on remote device] ************************************************** fatal: [veos01]: FAILED! => {"changed": false, "failed": true, "msg": "unable to open shell"} @@ -276,7 +276,7 @@ For example: or: -.. code-block:: none +.. code-block:: console TASK [ios_system : configure name_servers] ************************************************************* task path: @@ -303,7 +303,7 @@ Indicates that the remote host you are trying to connect to can not be reached For example: -.. code-block:: yaml +.. code-block:: text 2017-04-04 11:39:48,147 p=15299 u=fred | control socket path is /home/fred/.ansible/pc/ca5960d27a 2017-04-04 11:39:48,147 p=15299 u=fred | current working directory is /home/fred/git/ansible-inc/stable-2.3/test/integration @@ -332,7 +332,7 @@ Occurs if the credentials (username, passwords, or ssh keys) passed to ``ansible For example: -.. code-block:: yaml +.. code-block:: text ESTABLISH CONNECTION FOR USER: cisco on PORT 22 TO ios01 Authentication failed. @@ -342,7 +342,7 @@ Suggestions to resolve: If you are specifying credentials through ``password:`` (either directly or through ``provider:``) or the environment variable `ANSIBLE_NET_PASSWORD` it is possible that ``paramiko`` (the Python SSH library that Ansible uses) is using ssh keys, and therefore the credentials you are specifying are being ignored. To find out if this is the case, disable "look for keys". This can be done like this: -.. code-block:: yaml +.. code-block:: shell export ANSIBLE_PARAMIKO_LOOK_FOR_KEYS=False @@ -363,7 +363,7 @@ When using persistent connections with Paramiko, the connection runs in a backgr For example: -.. code-block:: yaml +.. code-block:: text 2017-04-04 12:06:03,486 p=17981 u=fred | using connection plugin network_cli 2017-04-04 12:06:04,680 p=17981 u=fred | connecting to host veos01 returned an error @@ -412,7 +412,7 @@ Error: "No authentication methods available" For example: -.. code-block:: yaml +.. code-block:: text 2017-04-04 12:19:05,670 p=18591 u=fred | creating new control socket for host veos01:None as user admin 2017-04-04 12:19:05,670 p=18591 u=fred | control socket path is /home/fred/.ansible/pc/ca5960d27a @@ -451,7 +451,7 @@ Persistent connection idle timeout By default, ``ANSIBLE_PERSISTENT_CONNECT_TIMEOUT`` is set to 30 (seconds). You may see the following error if this value is too low: -.. code-block:: yaml +.. code-block:: text 2017-04-04 12:19:05,670 p=18591 u=fred | persistent connection idle timeout triggered, timeout value is 30 secs @@ -459,7 +459,7 @@ Suggestions to resolve: Increase value of persistent connection idle timeout: -.. code-block:: sh +.. code-block:: shell export ANSIBLE_PERSISTENT_CONNECT_TIMEOUT=60 @@ -477,7 +477,7 @@ By default, ``ANSIBLE_PERSISTENT_COMMAND_TIMEOUT`` is set to 30 (seconds). Prior You may see the following error if this value is too low: -.. code-block:: yaml +.. code-block:: text 2017-04-04 12:19:05,670 p=18591 u=fred | command timeout triggered, timeout value is 30 secs @@ -486,7 +486,7 @@ Suggestions to resolve: * Option 1 (Global command timeout setting): Increase value of command timeout in configuration file or by setting environment variable. - .. code-block:: yaml + .. code-block:: shell export ANSIBLE_PERSISTENT_COMMAND_TIMEOUT=60 @@ -510,7 +510,7 @@ Suggestions to resolve: Suggestions to resolve: Some modules support a ``timeout`` option, which is different to the ``timeout`` keyword for tasks. - + .. code-block:: yaml - name: save running-config @@ -521,7 +521,7 @@ Suggestions to resolve: Suggestions to resolve: - + If the module does not support the ``timeout`` option directly, most networking connection plugins can enable similar functionality with the ``ansible_command_timeout`` variable. .. code-block:: yaml @@ -543,7 +543,7 @@ Persistent connection retry timeout By default, ``ANSIBLE_PERSISTENT_CONNECT_RETRY_TIMEOUT`` is set to 15 (seconds). You may see the following error if this value is too low: -.. code-block:: yaml +.. code-block:: text 2017-04-04 12:19:35,708 p=18591 u=fred | connect retry timeout expired, unable to connect to control socket 2017-04-04 12:19:35,709 p=18591 u=fred | persistent_connect_retry_timeout is 15 secs @@ -555,7 +555,7 @@ Note: This value should be greater than the SSH timeout value (the timeout value section in the configuration file) and less than the value of the persistent connection idle timeout (connect_timeout). -.. code-block:: yaml +.. code-block:: shell export ANSIBLE_PERSISTENT_CONNECT_RETRY_TIMEOUT=30 @@ -668,7 +668,7 @@ network device by first connecting to the host specified in You can also set the proxy target for all hosts by using environment variables. -.. code-block:: sh +.. code-block:: shell export ANSIBLE_SSH_ARGS='-o ProxyCommand="ssh -W %h:%p -q bastion01"' @@ -693,7 +693,7 @@ from the given custom ssh file path Example ssh config file (~/.ssh/config) --------------------------------------- -.. code-block:: ini +.. code-block:: shell Host jumphost HostName jumphost.domain.name.com diff --git a/docs/docsite/rst/os_guide/windows_ssh.rst b/docs/docsite/rst/os_guide/windows_ssh.rst index e55b9049b00..a141efcbeb3 100644 --- a/docs/docsite/rst/os_guide/windows_ssh.rst +++ b/docs/docsite/rst/os_guide/windows_ssh.rst @@ -128,7 +128,7 @@ SSH key authentication on Windows works in the same way as SSH key authenticatio One difference is that the ``authorized_keys`` file for admin users is not located in the ``.ssh`` folder in the user's profile directory but in ``C:\ProgramData\ssh\administrators_authorized_keys``. It is possible to change the location of the ``authorized_keys`` file for admin users back to the user profile directory by removing, or commenting, the lines in ``C:\ProgramData\ssh\sshd_config`` and restarting the ``sshd`` service. -.. code-block:: +.. code-block:: shell Match Group administrators AuthorizedKeysFile __PROGRAMDATA__/ssh/administrators_authorized_keys diff --git a/docs/docsite/rst/playbook_guide/playbooks_templating.rst b/docs/docsite/rst/playbook_guide/playbooks_templating.rst index 506a17dab3e..5f828c8d9fb 100644 --- a/docs/docsite/rst/playbook_guide/playbooks_templating.rst +++ b/docs/docsite/rst/playbook_guide/playbooks_templating.rst @@ -19,15 +19,15 @@ Ansible parses templates on the control node and passes only the information nee .. note:: Files and data used by the :ref:`template module ` must be utf-8 encoded. - + Jinja2 Example ================== In this example, we want to write the server hostname to its /tmp/hostname. Our directory looks like this: - -.. code-block:: + +.. code-block:: console ├── hostname.yml ├── templates @@ -51,7 +51,7 @@ Our test.j2: .. code-block:: yaml My name is {{ ansible_facts['hostname'] }} - + .. seealso:: diff --git a/docs/docsite/rst/reference_appendices/general_precedence.rst b/docs/docsite/rst/reference_appendices/general_precedence.rst index 7beb76b1c73..768d8989757 100644 --- a/docs/docsite/rst/reference_appendices/general_precedence.rst +++ b/docs/docsite/rst/reference_appendices/general_precedence.rst @@ -167,7 +167,7 @@ This category only applies to things that take direct options, generally modules Outside of task actions, the most recognizable 'direct assignments' are with lookup, filter and test plugins: -.. code:: +.. code:: jinja lookup('plugin', direct1='value', direct2='value2')