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 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 new file mode 100644 index 00000000000..b4411764c9e --- /dev/null +++ b/tests/constraints-base.in @@ -0,0 +1,4 @@ +# Known limitations for indirect/transitive dependencies. + +rstcheck>=6.2.4 +sphinx-rtd-theme>=2.0.0 # Fix 404 pages with new sphinx -- https://github.com/ansible/ansible-documentation/issues/678