Backport/2.9/docs (#63814)

* Replaced old DSC links that given 404 (#63556)
Replace DSC links that returned "not found" with updated, working links.

(cherry picked from commit f638f29e44)

* Fix example in pip module documentation (#63462)

(cherry picked from commit d8b9f9fb4f)

* Update vmware ansible modules requirements section (#62797)
Update vSphere Automation Python SDK to the requirement section

Signed-off-by: Jobin George <jgeorge@vmware.com>
Signed-off-by: Abhijeet Kasurde <akasurde@redhat.com>
(cherry picked from commit 8a77f17dea)

* Typo usersername should be username (#63671)

(cherry picked from commit 2ef4ac1404)

* Update description for firstmatch option (#62896)

Fixes issue https://github.com/ansible/ansible/issues/62862. The edit makes the description for the `firstmatch` option clearer. The `firstmatch` option was introduced by PR https://github.com/ansible/ansible/pull/33825

(cherry picked from commit aeb0dde7cc)

* Update win_regmerge.py (#63633)
s/windows/Windows/ in title

(cherry picked from commit 4326165be5)

* Example incorrect: server_url is required argument (#63670)
The example "Delete GitLab Group" does not work - requires server_url parameter. This likely applies to all Examples, so this change proposes at least putting in the required parameter in the examples. In future we can remove the soon-to-be deprecated server_url parameter.

(cherry picked from commit b02467961a)

* doc: win_user: fix typo in the description of the groups modifyer (#63743)

(cherry picked from commit 6046386dba)

* Update AWS dev guide to recommend module_defaults and point to CI policy repo (#63589)

(cherry picked from commit 9cda5819b9)

* Add example for port range to win_firewall_rule_module (#63269)

(cherry picked from commit 2e81b813dd)

* added a link to install instruction of OpenSSH (#63548)

(cherry picked from commit cfe2beae46)

docs/docsite/rst/dev_guide/platforms/aws_guidelines.rst

@@ -639,14 +639,14 @@ to your test in the following variables:
 * `aws_secret_key`
 * `security_token`
 
-So all invocations of AWS modules in the test should set these parameters. To avoid duplication these
+So all invocations of AWS modules in the test should set these parameters. To avoid duplicating these
-for every call, it's preferable to use `YAML Anchors <https://blog.daemonl.com/2016/02/yaml.html>`_. For example:
+for every call, it's preferable to use :ref:`module_defaults <module_defaults>`. For example:
 
 .. code-block:: yaml
 
    - name: set connection information for all tasks
-     set_fact:
+     module_defaults:
-       aws_connection_info: &aws_connection_info
+       group/aws:
          aws_access_key: "{{ aws_access_key }}"
          aws_secret_key: "{{ aws_secret_key }}"
          security_token: "{{ security_token }}"
@@ -656,12 +656,10 @@ for every call, it's preferable to use `YAML Anchors <https://blog.daemonl.com/2
    - name: Do Something
      ec2_instance:
        ... params ...
-       <<: *aws_connection_info
 
    - name: Do Something Else
      ec2_instance:
        ... params ...
-       <<: *aws_connection_info
 
 AWS Permissions for Integration Tests
 -------------------------------------
@@ -694,7 +692,7 @@ To start with the most permissive IAM policy:
 3) Modify your policy to allow only the actions your tests use. Restrict account, region, and prefix where possible. Wait a few minutes for your policy to update.
 4) Run the tests again with a user or role that allows only the new policy.
 5) If the tests fail, troubleshoot (see tips below), modify the policy, run the tests again, and repeat the process until the tests pass with a restrictive policy.
-6) Share the minimum policy in a comment on your PR.
+6) Open a pull request proposing the minimum required policy to the `testing policies <https://github.com/mattclay/aws-terminator/tree/master/aws/policy>`_.
 
 To start from the least permissive IAM policy:
 
@@ -711,7 +709,7 @@ To start from the least permissive IAM policy:
 3) Add the action or resource that caused the failure to `an IAM policy <https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_create.html#access_policies_create-start>`_. Wait a few minutes for your policy to update.
 4) Run the tests again with this policy attached to your user or role.
 5) If the tests still fail at the same place with the same error you will need to troubleshoot (see tips below). If the first test passes, repeat steps 2 and 3 for the next error. Repeat the process until the tests pass with a restrictive policy.
-6) Share the minimum policy in a comment on your PR.
+6) Open a pull request proposing the minimum required policy to the `testing policies <https://github.com/mattclay/aws-terminator/tree/master/aws/policy>`_.
 
 Troubleshooting IAM policies
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^

docs/docsite/rst/scenario_guides/vmware_scenarios/vmware_intro.rst

@@ -23,7 +23,17 @@ and vCenter infrastructure. You can install pyVmomi using pip:
 
     $ pip install pyvmomi
 
+Ansible VMware modules leveraging latest vSphere(6.0+) features are using `vSphere Automation Python SDK <https://github.com/vmware/vsphere-automation-sdk-python>`_. The vSphere Automation Python SDK also has client libraries, documentation, and sample code for VMware Cloud on AWS Console APIs, NSX VMware Cloud on AWS integration APIs, VMware Cloud on AWS site recovery APIs, NSX-T APIs.
 
+You can install vSphere Automation Python SDK using pip:
+
+.. code-block:: bash
+
+     $ pip install --upgrade git+https://github.com/vmware/vsphere-automation-sdk-python.git
+
+Note:
+   Installing vSphere Automation Python SDK also installs ``pyvmomi``. A separate installation of ``pyvmomi`` is not required.
+   
 vmware_guest module
 ===================
 

docs/docsite/rst/user_guide/windows_dsc.rst

@@ -12,7 +12,7 @@ is the same as Ansible, it is just executed in a different manner. Since
 Ansible 2.4, the ``win_dsc`` module has been added and can be used to leverage
 existing DSC resources when interacting with a Windows host.
 
-More details on DSC can be viewed at `DSC Overview <https://docs.microsoft.com/en-us/powershell/dsc/overview>`_.
+More details on DSC can be viewed at `DSC Overview <https://docs.microsoft.com/en-us/powershell/scripting/dsc/overview/overview>`_.
 
 Host Requirements
 `````````````````
@@ -27,7 +27,7 @@ Why Use DSC?
 ````````````
 DSC and Ansible modules have a common goal which is to define and ensure the state of a
 resource. Because of
-this, resources like the DSC `File resource <https://docs.microsoft.com/en-us/powershell/dsc/fileresource>`_
+this, resources like the DSC `File resource <https://docs.microsoft.com/en-us/powershell/scripting/dsc/reference/resources/windows/fileresource>`_
 and Ansible ``win_file`` can be used to achieve the same result. Deciding which to use depends
 on the scenario.
 
@@ -59,9 +59,9 @@ How to Use DSC?
 ```````````````
 The ``win_dsc`` module takes in a free-form of options so that it changes
 according to the resource it is managing. A list of built in resources can be
-found at `resources <https://docs.microsoft.com/en-us/powershell/dsc/resources>`_.
+found at `resources <https://docs.microsoft.com/en-us/powershell/scripting/dsc/resources/resources>`_.
 
-Using the `Registry <https://docs.microsoft.com/en-us/powershell/dsc/registryresource>`_
+Using the `Registry <https://docs.microsoft.com/en-us/powershell/scripting/dsc/reference/resources/windows/registryresource>`_
 resource as an example, this is the DSC definition as documented by Microsoft:
 
 .. code-block:: powershell

docs/docsite/rst/user_guide/windows_faq.rst

@@ -169,7 +169,7 @@ to manage Windows hosts. To connect to Windows hosts over SSH, you must install
 fork that is in development with Microsoft on
 the Windows host(s). While most of the basics should work with SSH,
 ``Win32-OpenSSH`` is rapidly changing, with new features added and bugs
-fixed in every release. It is highly recommend you install the latest release
+fixed in every release. It is highly recommend you `install <https://github.com/PowerShell/Win32-OpenSSH/wiki/Install-Win32-OpenSSH>`_ the latest release
 of ``Win32-OpenSSH`` from the GitHub Releases page when using it with Ansible
 on Windows hosts.
 

lib/ansible/modules/files/lineinfile.py

@@ -116,7 +116,7 @@ options:
   firstmatch:
     description:
       - Used with C(insertafter) or C(insertbefore).
-      - If set, C(insertafter) and C(insertbefore) find a first line has regular expression matches.
+      - If set, C(insertafter) and C(insertbefore) will work with the first line that matches the given regular expression.
     type: bool
     default: no
     version_added: "2.5"

lib/ansible/modules/packaging/language/pip.py

@@ -97,7 +97,7 @@ options:
     description:
       - The explicit executable or pathname for the pip executable,
         if different from the Ansible Python interpreter. For
-        example C(pip-3.3), if there are both Python 2.7 and 3.3 installations
+        example C(pip3.3), if there are both Python 2.7 and 3.3 installations
         in the system and you want to run pip for the Python 3.3 installation.
       - Mutually exclusive with I(virtualenv) (added in 2.1).
       - Does not affect the Ansible Python interpreter.
@@ -212,10 +212,10 @@ EXAMPLES = '''
     requirements: /my_app/requirements.txt
     extra_args: "--no-index --find-links=file:///my_downloaded_packages_dir"
 
-# Install (Bottle) for Python 3.3 specifically,using the 'pip-3.3' executable.
+# Install (Bottle) for Python 3.3 specifically,using the 'pip3.3' executable.
 - pip:
     name: bottle
-    executable: pip-3.3
+    executable: pip3.3
 
 # Install (Bottle), forcing reinstallation if it's already installed
 - pip:

lib/ansible/modules/source_control/gitlab_group.py

@@ -88,7 +88,7 @@ options:
 EXAMPLES = '''
 - name: "Delete GitLab Group"
   gitlab_group:
-    api_url: https://gitlab.example.com/
+    server_url: https://gitlab.example.com/
     api_token: "{{ access_token }}"
     validate_certs: False
     name: my_first_group
@@ -96,9 +96,9 @@ EXAMPLES = '''
 
 - name: "Create GitLab Group"
   gitlab_group:
-    api_url: https://gitlab.example.com/
+    server_url: https://gitlab.example.com/
     validate_certs: True
-    api_usersername: dj-wasabi
+    api_username: dj-wasabi
     api_password: "MySecretPassword"
     name: my_first_group
     path: my_first_group
@@ -107,9 +107,9 @@ EXAMPLES = '''
 # The group will by created at https://gitlab.dj-wasabi.local/super_parent/parent/my_first_group
 - name: "Create GitLab SubGroup"
   gitlab_group:
-    api_url: https://gitlab.example.com/
+    server_url: https://gitlab.example.com/
     validate_certs: True
-    api_usersername: dj-wasabi
+    api_username: dj-wasabi
     api_password: "MySecretPassword"
     name: my_first_group
     path: my_first_group

lib/ansible/modules/windows/win_firewall_rule.py

@@ -144,4 +144,13 @@ EXAMPLES = r'''
     protocol: tcp
     state: present
     enabled: yes
+- name: Firewall rule to allow port range
+  win_firewall_rule:
+    name: Sample port range
+    localport: 5000-5010
+    action: allow
+    direction: in
+    protocol: tcp
+    state: present
+    enabled: yes
 '''

lib/ansible/modules/windows/win_regmerge.py

@@ -15,7 +15,7 @@ DOCUMENTATION = r'''
 ---
 module: win_regmerge
 version_added: "2.1"
-short_description: Merges the contents of a registry file into the windows registry
+short_description: Merges the contents of a registry file into the Windows registry
 description:
     - Wraps the reg.exe command to import the contents of a registry file.
     - Suitable for use with registry files created using M(win_template).

lib/ansible/modules/windows/win_user.py

@@ -78,7 +78,7 @@ options:
     version_added: "1.9"
   groups:
     description:
-      - Adds or removes the user from this comma-separated lis of groups,
+      - Adds or removes the user from this comma-separated list of groups,
         depending on the value of I(groups_action).
       - When I(groups_action) is C(replace) and I(groups) is set to the empty
         string ('groups='), the user is removed from all groups.