Fix RST syntax and resolve rstcheck validation errors

ganeshhubale · ganeshhubale · commit 69732e8a1b94 · 2025-01-29T22:35:25.000+05:30
- 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 &lt;ganeshhubale03@gmail.com&gt;
diff --git 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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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:: ini
 
    ansible_password: !vault |
           $ANSIBLE_VAULT;1.2;AES256;my_user
@@ -374,7 +374,7 @@ The :option:`--vault-id <ansible-playbook --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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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<unsafe_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 <https://yaml.org/spec/1.2/spec.html#id2765878>`_ 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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
