Backport hactoberfest 1 (#79065)

* apt_key, fix example indentation

Co-authored-by: Matt Clay <matt@mystile.com>
(cherry picked from commit cee9872605)

* Docs: Add code-block wrappers to code examples: testing_documentation.rst (#78966)

* Docs: Add code-block wrappers to code examples: testing_documentation.rst
List of changed files:
- docs/docsite/rst/dev_guide/testing_documentation.rst
* Fix: match whitespace convention of other occurences

(cherry picked from commit 538b99781f)

* added code-blocks according to #78962 (#78972)

(cherry picked from commit 01484cdc68)

* Adding code-block wrappers to code examples (#78968)

(cherry picked from commit 1db75a41bf)

* added code-blocks according to #78963 (#78969)

* added code-blocks according to  #78963
* Update testing.rst, added newlines

(cherry picked from commit 446406a0c8)

* Docs: Add code-block wrappers to code examples in style_guide (#78970)

* Docs: Add code-block wrappers to code examples in style_guide
List of changed files:
- docs/docsite/rst/dev-guide/style_guide/index.rst
- docs/docsite/rst/dev-guide/style_guide/basic_rules.rst

(cherry picked from commit 3dc0c2135e)

* #78971 Update module_lifecycle.rst (#78974)

* Update module_lifecycle.rst

(cherry picked from commit 93c2cb2b8e)

* #78965 Adding the code-block to prevent the translation (#78979)

* Adding the code-block to prevent the translation

(cherry picked from commit 9afb37eda6)

* Adds code-block in collection documentation (#78977)

* fix issue #78976

(cherry picked from commit 1b922b42dd)

* docs - Use code-block to format examples in Windows module development walkthrough (#78985)

(cherry picked from commit 56c48d1c45)

* Docs: true/false with boolean values in docsite/rst/os_guide (#78957)

(cherry picked from commit fb8c2daf46)

* Update porting_guide_2.0.rst (#78951)

Replaced http link with rst version - issue https://github.com/ansible/ansible/issues/78914

(cherry picked from commit dc2d15fca4)

* Update porting_guide_3.rst (#78952)

Fixes #78914

(cherry picked from commit 919c449256)

* Update porting_guide_4.rst (#78953)

(cherry picked from commit ba32642538)

* Update porting_guide_5.rst (#78954)

(cherry picked from commit 5137cb16e9)

* scenario guide doc changes (#78934)

(cherry picked from commit 5b333c9665)

Co-authored-by: Jasper <44026484+jasperjonker@users.noreply.github.com>
Co-authored-by: Ozan Uslan <54141068+ozanuslan@users.noreply.github.com>
Co-authored-by: Lukas Grimm <ombre@ombre.ch>
Co-authored-by: Deepshri M <92997066+Deepshaded@users.noreply.github.com>
Co-authored-by: IMvision12 <88665786+IMvision12@users.noreply.github.com>
Co-authored-by: Luigi Giugliano <luigi3000@gmail.com>
Co-authored-by: Thomas Doczkal <thomas@doczkal.eu>
Co-authored-by: jmakhack <joshmak@berkeley.edu>
Co-authored-by: Sudipto Ghosh <sudipto@ghosh.pro>
Co-authored-by: Kampftoast <creeper00001@googlemail.com>
Co-authored-by: J-F-Far <joel.f.farthing@gmail.com>

docs/docsite/rst/dev_guide/developing_collections_distributing.rst

@@ -132,7 +132,9 @@ After configuring one or more distribution servers, build a collection tarball.
 
     collection_dir#> ansible-galaxy collection build
 
-This command builds a tarball of the collection in the current directory, which you can upload to your selected distribution server::
+This command builds a tarball of the collection in the current directory, which you can upload to your selected distribution server:
+
+.. code-block:: shell
 
     my_collection/
     ├── galaxy.yml

docs/docsite/rst/dev_guide/developing_module_utilities.rst

@@ -20,7 +20,9 @@ resolving those matching the namespace against a :ref:`search path <ansible_sear
 active configuration.
 
 To reduce the maintenance burden in a collection or in local modules, you can extract
-duplicated code into one or more module utilities and import them into your modules. For example, if you have your own custom modules that import a ``my_shared_code`` library, you can place that into a ``./module_utils/my_shared_code.py`` file like this::
+duplicated code into one or more module utilities and import them into your modules. For example, if you have your own custom modules that import a ``my_shared_code`` library, you can place that into a ``./module_utils/my_shared_code.py`` file like this:
+
+.. code-block:: python
 
   from ansible.module_utils.my_shared_code import MySharedCodeClient
 

docs/docsite/rst/dev_guide/developing_modules_general_windows.rst

@@ -412,7 +412,9 @@ PowerShell utils, these are stored in a folder called ``module_utils`` and the f
 
 The below example is a role structure that contains two PowerShell custom module_utils called
 ``Ansible.ModuleUtils.ModuleUtil1``, ``Ansible.ModuleUtils.ModuleUtil2``, and a C# util containing the namespace
-``Ansible.CustomUtil``::
+``Ansible.CustomUtil``:
+
+.. code-block:: console
 
     meta/
       main.yml
@@ -561,7 +563,9 @@ You can test a module with an Ansible playbook. For example:
 - Create a playbook in any directory ``touch testmodule.yml``.
 - Create an inventory file in the same directory ``touch hosts``.
 - Populate the inventory file with the variables required to connect to a Windows host(s).
-- Add the following to the new playbook file::
+- Add the following to the new playbook file:
+
+.. code-block:: yaml
 
     ---
     - name: test out windows module

docs/docsite/rst/dev_guide/module_lifecycle.rst

@@ -69,13 +69,13 @@ Changing a module or plugin name in the Ansible main repository
 ===============================================================
 
 You can also rename a module and keep a deprecated alias to the old name by using a symlink that starts with _.
-This example allows the ``stat`` module to be called with ``fileinfo``, making the following examples equivalent::
+This example allows the ``stat`` module to be called with ``fileinfo``, making the following examples equivalent:
+
+.. code-block:: yaml
     
-    EXAMPLES = '''
     ln -s stat.py _fileinfo.py
     ansible -m stat -a "path=/tmp" localhost
     ansible -m fileinfo -a "path=/tmp" localhost
-    '''
 
 Renaming a module or plugin in a collection, or redirecting a module or plugin to another collection
 ====================================================================================================

docs/docsite/rst/dev_guide/style_guide/basic_rules.rst

@@ -61,7 +61,9 @@ For menu procedures, bold the menu names, button names, and so on to help the us
 3. In the **Open** dialog box, click **Save**.
 4. On the toolbar, click the **Open File** icon.
 
-For code or command snippets, use the RST `code-block directive <https://www.sphinx-doc.org/en/1.5/markup/code.html#directive-code-block>`_::
+For code or command snippets, use the RST `code-block directive <https://www.sphinx-doc.org/en/1.5/markup/code.html#directive-code-block>`_:
+
+.. code-block:: rst
 
    .. code-block:: bash
 

docs/docsite/rst/dev_guide/style_guide/index.rst

@@ -192,7 +192,9 @@ Adding anchors
 
 * Include at least one anchor on every page
 * Place the main anchor above the main header
-* If the file has a unique title, use that for the main page anchor::
+* If the file has a unique title, use that for the main page anchor:
+
+.. code-block:: text
 
    .. _unique_page::
 

docs/docsite/rst/dev_guide/testing.rst

@@ -129,7 +129,9 @@ Create a fresh area to work:
    git clone https://github.com/ansible/ansible.git ansible-pr-testing
    cd ansible-pr-testing
 
-Next, find the pull request you'd like to test and make note of its number. It will look something like this::
+Next, find the pull request you'd like to test and make note of its number. It will look something like this:
+
+.. code-block:: text
 
    Use os.path.sep instead of hardcoding / #65381
 
@@ -204,7 +206,9 @@ More information: :ref:`testing_integration`
 
 Any potential issues should be added as comments on the pull request (and it's acceptable to comment if the feature works as well), remembering to include the output of ``ansible --version``
 
-Example::
+Example:
+
+.. code-block:: text
 
    Works for me! Tested on `Ansible 2.3.0`.  I verified this on CentOS 6.5 and also Ubuntu 14.04.
 

docs/docsite/rst/dev_guide/testing/sanity/ignores.rst

@@ -71,7 +71,9 @@ This will be the name of the sanity test.
 If the sanity test is specific to a version of Python, the name will include a dash (``-``) and the relevant Python version.
 If the named test uses error codes then the error code to ignore must be appended to the name of the test, separated by a colon (``:``).
 
-Below are some example ignore entries for an Ansible collection::
+Below are some example ignore entries for an Ansible collection:
+
+.. code-block:: text
 
     roles/my_role/files/my_script.sh shellcheck:SC2154 # ignore undefined variable
     plugins/modules/my_module.py validate-modules:missing-gplv3-license # ignore license check
@@ -81,7 +83,9 @@ It is also possible to skip a sanity test for a specific file.
 This is done by adding ``!skip`` after the sanity test name in the second column.
 When this is done, no error code is included, even if the sanity test uses error codes.
 
-Below are some example skip entries for an Ansible collection::
+Below are some example skip entries for an Ansible collection:
+
+.. code-block:: text
 
     plugins/module_utils/my_util.py validate-modules!skip # waiting for bug fix in module validator
     plugins/lookup/my_plugin.py compile-2.6!skip # Python 2.6 is not supported on the controller

docs/docsite/rst/dev_guide/testing_documentation.rst

@@ -31,6 +31,8 @@ To ensure that your module documentation matches your ``argument_spec``:
 
       pip install --user -r test/lib/ansible_test/_data/requirements/sanity.txt
 
-#. run the ``validate-modules`` test::
+#. run the ``validate-modules`` test:
+
+   .. code-block:: bash
 
     ansible-test sanity --test validate-modules mymodule

docs/docsite/rst/dev_guide/testing_pep8.rst

@@ -13,8 +13,9 @@ PEP 8
 Running Locally
 ===============
 
-The `PEP 8`_ check can be run locally with::
+The `PEP 8`_ check can be run locally with:
 
+.. code-block:: shell
 
     ansible-test sanity --test pep8 [file-or-directory-path-to-check] ...
 

docs/docsite/rst/os_guide/intro_bsd.rst

@@ -129,7 +129,7 @@ For example, given the inventory
   [test:vars]
   ansible_connection=ssh
   ansible_user=admin
-  ansible_become=yes
+  ansible_become=true
   ansible_become_user=root
   ansible_become_method=sudo
   ansible_interpreter_python_fallback=['/usr/local/bin/python', '/usr/local/bin/python3', '/usr/local/bin/python3.8']
@@ -213,7 +213,7 @@ You can either ignore it or get rid of it by setting the variable ``ansible_pyth
   [test:vars]
   ansible_connection=ssh
   ansible_user=admin
-  ansible_become=yes
+  ansible_become=true
   ansible_become_user=root
   ansible_become_method=sudo
   ansible_interpreter_python_fallback=['/usr/local/bin/python', '/usr/local/bin/python3', '/usr/local/bin/python3.8']

docs/docsite/rst/os_guide/windows_dsc.rst

@@ -187,7 +187,7 @@ For example:
     SourceCredential_username: AdminUser
     SourceCredential_password: PasswordForAdminUser
 
-.. Note:: On versions of Ansible older than 2.8, you should set ``no_log: yes``
+.. Note:: On versions of Ansible older than 2.8, you should set ``no_log: true``
     on the task definition in Ansible to ensure any credentials used are not
     stored in any log file or console output.
 
@@ -205,10 +205,10 @@ For example, to define a ``[CimInstance]`` value in Ansible:
 
     # [CimInstance]AuthenticationInfo == MSFT_xWebAuthenticationInformation
     AuthenticationInfo:
-      Anonymous: no
-      Basic: yes
-      Digest: no
-      Windows: yes
+      Anonymous: false
+      Basic: true
+      Digest: false
+      Windows: true
 
 In the above example, the CIM instance is a representation of the class
 `MSFT_xWebAuthenticationInformation <https://github.com/dsccommunity/xWebAdministration/blob/master/source/DSCResources/MSFT_xWebSite/MSFT_xWebSite.schema.mof>`_.
@@ -317,7 +317,7 @@ to access the ``HKEY_CURRENT_USER`` hive of the Ansible user:
         ValueData: TestData
         PsDscRunAsCredential_username: '{{ ansible_user }}'
         PsDscRunAsCredential_password: '{{ ansible_password }}'
-      no_log: yes
+      no_log: true
 
 Custom DSC Resources
 ````````````````````
@@ -435,7 +435,7 @@ Interact with Azure
         ServiceName: ServiceName
         StorageAccountName: StorageAccountName
         InstanceSize: Medium
-        Windows: yes
+        Windows: true
         Ensure: Present
         Credential_username: '{{ ansible_user }}'
         Credential_password: '{{ ansible_password }}'
@@ -489,10 +489,10 @@ Setup IIS Website
           Port: 8080
           IPAddress: '*'
         AuthenticationInfo:
-          Anonymous: no
-          Basic: yes
-          Digest: no
-          Windows: yes
+          Anonymous: false
+          Basic: true
+          Digest: false
+          Windows: true
 
 .. seealso::
 

docs/docsite/rst/os_guide/windows_setup.rst

@@ -495,7 +495,7 @@ Ansible, select one of these installation options:
     # main.yml
     - name: install Win32-OpenSSH service
       hosts: windows
-      gather_facts: no
+      gather_facts: false
       roles:
       - role: jborean93.win_openssh
         opt_openssh_setup_service: True

docs/docsite/rst/os_guide/windows_usage.rst

@@ -161,8 +161,8 @@ access a folder on the same host:
         name: '{{ item.name }}'
         password: '{{ item.password }}'
         groups: LocalGroup
-        update_password: no
-        password_never_expires: yes
+        update_password: false
+        password_never_expires: true
       loop:
       - name: User1
         password: Password1
@@ -185,7 +185,7 @@ access a folder on the same host:
     - name: Remove parent inheritance of Development folder
       win_acl_inheritance:
         path: C:\Development
-        reorganize: yes
+        reorganize: true
         state: absent
 
 Domain
@@ -201,7 +201,7 @@ are created:
         name: '{{ item.name }}'
         upn: '{{ item.name }}@MY.DOMAIN.COM'
         password: '{{ item.password }}'
-        password_never_expires: no
+        password_never_expires: false
         groups:
         - Test User
         - Application

docs/docsite/rst/porting_guides/porting_guide_2.0.rst

@@ -92,7 +92,7 @@ uses key=value escaping which has not changed.  The other option is to check for
 
 * porting task includes
 * More dynamic. Corner-case formats that were not supposed to work now do not, as expected.
-* variables defined in the yaml dict format https://github.com/ansible/ansible/issues/13324
+* variables defined in the yaml dict format see `issue 13324 <https://github.com/ansible/ansible/issues/13324>`_
 * templating (variables in playbooks and template lookups) has improved with regard to keeping the original instead of turning everything into a string.
   If you need the old behavior, quote the value to pass it around as a string.
 * Empty variables and variables set to null in yaml are no longer converted to empty strings. They will retain the value of `None`.

docs/docsite/rst/porting_guides/porting_guide_3.rst

@@ -207,7 +207,7 @@ Breaking Changes
 Ansible-base
 ~~~~~~~~~~~~
 
-- ansible-galaxy login command has been removed (see https://github.com/ansible/ansible/issues/71560)
+- ansible-galaxy login command has been removed ( see `issue 71560 <https://github.com/ansible/ansible/issues/71560>`_)
 
 ansible.utils
 ~~~~~~~~~~~~~

docs/docsite/rst/porting_guides/porting_guide_4.rst

@@ -194,7 +194,7 @@ Breaking Changes
 community.zabbix
 ~~~~~~~~~~~~~~~~
 
-- all roles now reference other roles and modules via their fully qualified collection names, which makes Ansible 2.10 minimum supported version for roles (See https://github.com/ansible-collections/community.zabbix/pull/477).
+- all roles now reference other roles and modules via their fully qualified collection names, which makes Ansible 2.10 minimum supported version for roles (see `issue 477 <https://github.com/ansible-collections/community.zabbix/pull/477>`_).
 
 Deprecated Features
 -------------------
@@ -522,7 +522,7 @@ Known Issues
 Ansible-core
 ~~~~~~~~~~~~
 
-- ansible-test - The ``pylint`` sanity test no longer correctly detects "bad" variable names for non-constants. See https://github.com/PyCQA/pylint/issues/3701 for additional details.
+- ansible-test - The ``pylint`` sanity test no longer correctly detects "bad" variable names for non-constants. See `issue 3701 <https://github.com/PyCQA/pylint/issues/3701>`_ for additional details.
 
 dellemc.openmanage
 ~~~~~~~~~~~~~~~~~~
@@ -547,7 +547,7 @@ Ansible-core
 - NetBSD virtualization facts (specifically ``ansible_virtualization_type``) now returns a more accurate value by checking the value of the ``machdep.hypervisor`` ``sysctl`` key. This change is breaking because in some cases previously, we would erroneously report ``xen`` even when the target is not running on Xen. This prevents that behavior in most cases. (https://github.com/ansible/ansible/issues/69352)
 - Replaced the in-tree dependency resolver with an external implementation that pip >= 20.3 uses now by default — ``resolvelib``. (https://github.com/ansible/ansible/issues/71784)
 - The ``meta`` module now supports tags for user-defined tasks. Internal ``meta`` tasks continue to always run. (https://github.com/ansible/ansible/issues/64558)
-- ansible-galaxy login command has been removed (see https://github.com/ansible/ansible/issues/71560)
+- ansible-galaxy login command has been removed (see `issue 71560 <https://github.com/ansible/ansible/issues/71560>`_)
 
 ansible.netcommon
 ~~~~~~~~~~~~~~~~~

docs/docsite/rst/porting_guides/porting_guide_5.rst

@@ -441,7 +441,7 @@ Known Issues
 Ansible-core
 ~~~~~~~~~~~~
 
-- ansible-test - Tab completion anywhere other than the end of the command with the new composite options will provide incorrect results. See https://github.com/kislyuk/argcomplete/issues/351 for additional details.
+- ansible-test - Tab completion anywhere other than the end of the command with the new composite options will provide incorrect results. See `issue 351 <https://github.com/kislyuk/argcomplete/issues/351>`_ for additional details.
 
 dellemc.openmanage
 ~~~~~~~~~~~~~~~~~~
@@ -572,7 +572,7 @@ community.routeros
 community.zabbix
 ~~~~~~~~~~~~~~~~
 
-- all roles now reference other roles and modules via their fully qualified collection names, which makes Ansible 2.10 minimum supported version for roles (See https://github.com/ansible-collections/community.zabbix/pull/477).
+- all roles now reference other roles and modules via their fully qualified collection names, which makes Ansible 2.10 minimum supported version for roles (See `issue 477 <https://github.com/ansible-collections/community.zabbix/pull/477>`_).
 
 kubernetes.core
 ~~~~~~~~~~~~~~~

docs/docsite/rst/scenario_guides/guide_aci.rst

@@ -111,14 +111,14 @@ For this very reason, the modules need to run on the local Ansible controller (o
 
 Gathering facts
 ```````````````
-Because we run the modules on the Ansible controller gathering facts will not work. That is why when using these ACI modules it is mandatory to disable facts gathering. You can do this globally in your ``ansible.cfg`` or by adding ``gather_facts: no`` to every play.
+Because we run the modules on the Ansible controller gathering facts will not work. That is why when using these ACI modules it is mandatory to disable facts gathering. You can do this globally in your ``ansible.cfg`` or by adding ``gather_facts: false`` to every play.
 
 .. code-block:: yaml
    :emphasize-lines: 3
 
     - name: Another play in my playbook
       hosts: my-apic-1
-      gather_facts: no
+      gather_facts: false
       tasks:
       - name: Create a tenant
         aci_tenant:
@@ -235,7 +235,7 @@ By default, if an environment variable ``<protocol>_proxy`` is set on the target
 
 HTTP redirects can redirect from HTTP to HTTPS so ensure that the proxy environment for both protocols is correctly configured.
 
-If proxy support is not needed, but the system may have it configured nevertheless, use the parameter ``use_proxy: no`` to avoid accidental system proxy usage.
+If proxy support is not needed, but the system may have it configured nevertheless, use the parameter ``use_proxy: false`` to avoid accidental system proxy usage.
 
 .. hint:: Selective proxy support using the ``no_proxy`` environment variable is also supported.
 

docs/docsite/rst/scenario_guides/guide_azure.rst

@@ -460,7 +460,7 @@ Here is a simple playbook to exercise the Azure inventory script:
     - name: Test the inventory script
       hosts: azure
       connection: local
-      gather_facts: no
+      gather_facts: false
       tasks:
         - debug:
             msg: "{{ inventory_hostname }} has powerstate {{ powerstate }}"

docs/docsite/rst/scenario_guides/guide_gce.rst

@@ -89,7 +89,7 @@ you can use the following configuration:
 
    - name: Create IP address
      hosts: localhost
-     gather_facts: no
+     gather_facts: false
 
      vars:
        service_account_file: /home/my_account.json
@@ -168,7 +168,7 @@ rest.
 
    - name: Create an instance
      hosts: localhost
-     gather_facts: no
+     gather_facts: false
      vars:
          gcp_project: my-project
          gcp_cred_kind: serviceaccount

docs/docsite/rst/scenario_guides/guide_rax.rst

@@ -118,7 +118,7 @@ Here's what it would look like in a playbook, assuming the parameters were defin
             image: "{{ rax_image }}"
             count: "{{ rax_count }}"
             group: "{{ group }}"
-            wait: yes
+            wait: true
         register: rax
         delegate_to: localhost
 
@@ -442,9 +442,9 @@ Create an isolated cloud network and build a server
             region: IAD
             state: present
             count: 5
-            exact_count: yes
+            exact_count: true
             group: web
-            wait: yes
+            wait: true
             wait_timeout: 360
           register: rax
           delegate_to: localhost
@@ -473,7 +473,7 @@ Build a complete webserver environment with servers, custom networks and load ba
             type: PUBLIC
             timeout: 30
             region: IAD
-            wait: yes
+            wait: true
             state: present
             meta:
               app: my-cool-app
@@ -502,9 +502,9 @@ Build a complete webserver environment with servers, custom networks and load ba
             region: IAD
             state: present
             count: 5
-            exact_count: yes
+            exact_count: true
             group: web
-            wait: yes
+            wait: true
           register: rax
 
         - name: Add servers to web host group
@@ -525,7 +525,7 @@ Build a complete webserver environment with servers, custom networks and load ba
             port: 80
             condition: enabled
             type: primary
-            wait: yes
+            wait: true
             region: IAD
           loop: "{{ rax.success }}"
           when: rax.action == 'create'
@@ -583,9 +583,9 @@ Using a Control Machine
             region: DFW
             state: present
             count: 1
-            exact_count: yes
+            exact_count: true
             group: web
-            wait: yes
+            wait: true
           register: rax
 
         - name: Add servers to in memory groups
@@ -676,7 +676,7 @@ Using Ansible Pull
             - name: Wait for rackconnect automation to complete
               uri:
                 url: "https://{{ rax_region.stdout|trim }}.api.rackconnect.rackspace.com/v1/automation_status?format=json"
-                return_content: yes
+                return_content: true
               register: automation_status
               when: bootstrap.stat.exists != True
               until: automation_status['automation_status']|default('') == 'DEPLOYED'

docs/docsite/rst/scenario_guides/guide_scaleway.rst

@@ -70,7 +70,7 @@ The ``ssh_pub_key`` parameter contains your ssh public key as a string. Here is
 
     - name: Test SSH key lifecycle on a Scaleway account
       hosts: localhost
-      gather_facts: no
+      gather_facts: false
       environment:
         SCW_API_KEY: ""
 
@@ -120,7 +120,7 @@ Take a look at this short playbook to see a working example using ``scaleway_com
 
     - name: Test compute instance lifecycle on a Scaleway account
       hosts: localhost
-      gather_facts: no
+      gather_facts: false
       environment:
         SCW_API_KEY: ""
 

lib/ansible/modules/apt_key.py

@@ -90,8 +90,8 @@ EXAMPLES = '''
 
     - name: somerepo | apt source
       ansible.builtin.apt_repository:
-      repo: "deb [arch=amd64 signed-by=/etc/apt/trusted.gpg.d/somerepo.asc] https://download.example.com/linux/ubuntu {{ ansible_distribution_release }} stable"
-      state: present
+        repo: "deb [arch=amd64 signed-by=/etc/apt/trusted.gpg.d/myrepo.asc] https://download.example.com/linux/ubuntu {{ ansible_distribution_release }} stable"
+        state: present
 
 - name: Add an apt key by id from a keyserver
   ansible.builtin.apt_key: