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 f638f29e445b4e9e51d348ad0414c88cbaf67925)

* Fix example in pip module documentation (#63462)

(cherry picked from commit d8b9f9fb4f1d08693a6bcb724c66add7f265c8b5)

* 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 8a77f17dea7f479e755af64347fada0db0c90121)

* Typo usersername should be username (#63671)

(cherry picked from commit 2ef4ac140435f02c6cb2f55b09b2844dc078522a)

* 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 aeb0dde7ccb0b7ac34623241835cc876067b8c86)

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

(cherry picked from commit 4326165be56c1bc990d0e9eaef951227b0e94687)

* 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 b02467961a5d9357d48ea2d955bc4de69308a16c)

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

(cherry picked from commit 6046386dba6ed3ce5328cda56bc27ca168b29d4b)

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

(cherry picked from commit 9cda5819b95200b7ce3585e3171a5606cb715cec)

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

(cherry picked from commit 2e81b813ddfdd0b37c0d5fad34ec061c6f0eb079)

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

(cherry picked from commit cfe2beae46722c6e36188ba1691e3d58a3547dc3)

10 files changed, 41 insertions, 24 deletions

diff --git a/docs/docsite/rst/dev_guide/platforms/aws_guidelines.rst b/docs/docsite/rst/dev_guide/platforms/aws_guidelines.rst
index c0d706ade0..43e46dd1dd 100644
--- a/docs/docsite/rst/dev_guide/platforms/aws_guidelines.rst
+++ b/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
-for every call, it's preferable to use `YAML Anchors <https://blog.daemonl.com/2016/02/yaml.html>`_. For example:
+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 :ref:`module_defaults <module_defaults>`. For example:
 
 .. code-block:: yaml
 
    - name: set connection information for all tasks
-     set_fact:
-       aws_connection_info: &aws_connection_info
+     module_defaults:
+       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
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
diff --git a/docs/docsite/rst/scenario_guides/vmware_scenarios/vmware_intro.rst b/docs/docsite/rst/scenario_guides/vmware_scenarios/vmware_intro.rst
index 911d63fcdb..7006e66514 100644
--- a/docs/docsite/rst/scenario_guides/vmware_scenarios/vmware_intro.rst
+++ b/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
 ===================
 
diff --git a/docs/docsite/rst/user_guide/windows_dsc.rst b/docs/docsite/rst/user_guide/windows_dsc.rst
index a78f09b8eb..b8f1b41fee 100644
--- a/docs/docsite/rst/user_guide/windows_dsc.rst
+++ b/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
diff --git a/docs/docsite/rst/user_guide/windows_faq.rst b/docs/docsite/rst/user_guide/windows_faq.rst
index 6f2b511291..5c9da043bc 100644
--- a/docs/docsite/rst/user_guide/windows_faq.rst
+++ b/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.
 
diff --git a/lib/ansible/modules/files/lineinfile.py b/lib/ansible/modules/files/lineinfile.py
index 86bc44e4f2..b22d48960a 100644
--- a/lib/ansible/modules/files/lineinfile.py
+++ b/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"
diff --git a/lib/ansible/modules/packaging/language/pip.py b/lib/ansible/modules/packaging/language/pip.py
index bc06b39afe..598722a58b 100644
--- a/lib/ansible/modules/packaging/language/pip.py
+++ b/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:
diff --git a/lib/ansible/modules/source_control/gitlab_group.py b/lib/ansible/modules/source_control/gitlab_group.py
index 8203db7a33..975acf4b38 100644
--- a/lib/ansible/modules/source_control/gitlab_group.py
+++ b/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
diff --git a/lib/ansible/modules/windows/win_firewall_rule.py b/lib/ansible/modules/windows/win_firewall_rule.py
index 52e4c6e41b..d55d99d154 100644
--- a/lib/ansible/modules/windows/win_firewall_rule.py
+++ b/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
 '''
diff --git a/lib/ansible/modules/windows/win_regmerge.py b/lib/ansible/modules/windows/win_regmerge.py
index 98d7b6cc63..1b5596f945 100644
--- a/lib/ansible/modules/windows/win_regmerge.py
+++ b/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).
diff --git a/lib/ansible/modules/windows/win_user.py b/lib/ansible/modules/windows/win_user.py
index 7cca668972..5fc0633d06 100644
--- a/lib/ansible/modules/windows/win_user.py
+++ b/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.