doc: update doc on inventory/host section for provisioner (#3571)

* doc: update doc on inventory/host section for povisioner

1. Fix incorrect example, as 'hosts' should be two times, first
   time as a name for for 'inventory' section, and second, as
   normal ansible `hosts` stanza in the group.

2. Add well-known fact about incompatibility of sections of
   inventory and links.

* pylint

Co-authored-by: Sorin Sbarnea <[email protected]>

Author: amarao

src/molecule/provisioner/ansible.py

@@ -19,6 +19,7 @@
 #  DEALINGS IN THE SOFTWARE.
 """Ansible Provisioner Module."""
 
+# pylint: disable=too-many-lines
 import collections
 import copy
 import logging
@@ -296,8 +297,9 @@ class Ansible(base.Base):
           inventory:
             hosts:
               all:
-                extra_host:
-                  foo: hello
+                hosts:
+                  extra_host:
+                    foo: hello
 
     .. important::
 
@@ -332,6 +334,7 @@ class Ansible(base.Base):
         The only valid keys are ``hosts``, ``group_vars`` and ``host_vars``.  Molecule's
         schema validator will enforce this.
 
+
     .. code-block:: yaml
 
         provisioner:
@@ -342,6 +345,25 @@ class Ansible(base.Base):
               group_vars: ../../../inventory/group_vars/
               host_vars: ../../../inventory/host_vars/
 
+    .. important::
+
+        You can use either `hosts`/`group_vars`/`host_vars` sections of inventory OR `links`.
+        If you use both, links will win.
+
+    .. code-block:: yaml
+
+        provisioner:
+          name: ansible
+          hosts:
+            all:
+              hosts:
+                ignored:
+                   important: this host is ignored
+          inventory:
+            links:
+              hosts: ../../../inventory/hosts
+
+
     Override connection options:
 
     .. code-block:: yaml