adds FAQ TOC entry, links & examples to modules (#38706)

* adds FAQ TOC entry, links & examples to modules
* moves link to Notes, corrects examples

docs/docsite/rst/network/index.rst

@@ -32,6 +32,7 @@ For documentation on using a particular network module, consult the :doc:`list o
    :caption: User Guide
 
    user_guide/index
+   user_guide/faq
    user_guide/network_best_practices_2.5
    user_guide/network_debug_troubleshooting
    user_guide/network_working_with_command_output

lib/ansible/modules/network/eos/eos_config.py

@@ -36,6 +36,8 @@ description:
 extends_documentation_fragment: eos
 notes:
   - Tested against EOS 4.15
+  - Abbreviated commands are NOT idempotent, see
+    L(Network FAQ,../network/user_guide/faq.html#why-do-the-config-modules-always-return-changed-true-with-abbreviated-commands).
 options:
   lines:
     description:
@@ -235,6 +237,14 @@ EXAMPLES = """
   eos_config:
     diff_against: intended
     intended_config: "{{ lookup('file', 'master.cfg') }}"
+
+- name: for idempotency, use full-form commands
+  eos_config:
+    lines:
+      # - shut
+      - shutdown
+    # parents: int eth1
+    parents: interface Ethernet1
 """
 
 RETURN = """

lib/ansible/modules/network/ios/ios_config.py

@@ -35,6 +35,8 @@ description:
 extends_documentation_fragment: ios
 notes:
   - Tested against IOS 15.6
+  - Abbreviated commands are NOT idempotent, see
+    L(Network FAQ,../network/user_guide/faq.html#why-do-the-config-modules-always-return-changed-true-with-abbreviated-commands).
 options:
   lines:
     description:
@@ -262,6 +264,14 @@ EXAMPLES = """
 - name: save running to startup when modified
   ios_config:
     save_when: modified
+
+- name: for idempotency, use full-form commands
+  ios_config:
+    lines:
+      # - shut
+      - shutdown
+    # parents: int gig1/0/11
+    parents: interface GigabitEthernet1/0/11
 """
 
 RETURN = """

lib/ansible/modules/network/iosxr/iosxr_config.py

@@ -27,6 +27,8 @@ extends_documentation_fragment: iosxr
 notes:
   - Tested against IOS XRv 6.1.2
   - This module does not support netconf connection
+  - Abbreviated commands are NOT idempotent, see
+    L(Network FAQ,../network/user_guide/faq.html#why-do-the-config-modules-always-return-changed-true-with-abbreviated-commands).
   - Avoid service disrupting changes (viz. Management IP) from config replace.
   - Do not use C(end) in the replace config file.
 options:
@@ -152,6 +154,14 @@ EXAMPLES = """
     src: config.cfg
     replace: config
     backup: yes
+
+- name: for idempotency, use full-form commands
+  iosxr_config:
+    lines:
+      # - shut
+      - shutdown
+    # parents: int g0/0/0/1
+    parents: interface GigabitEthernet0/0/0/1
 """
 
 RETURN = """

lib/ansible/modules/network/junos/junos_config.py

@@ -127,6 +127,8 @@ requirements:
 notes:
   - This module requires the netconf system service be enabled on
     the remote device being managed.
+  - Abbreviated commands are NOT idempotent, see
+    L(Network FAQ,../network/user_guide/faq.html#why-do-the-config-modules-always-return-changed-true-with-abbreviated-commands).
   - Loading JSON-formatted configuration I(json) is supported
     starting in Junos OS Release 16.1 onwards.
   - Tested against vSRX JUNOS version 15.1X49-D15.4, vqfx-10000 JUNOS Version 15.1X53-D60.4.
@@ -158,6 +160,12 @@ EXAMPLES = """
 - name: confirm a previous commit
   junos_config:
     confirm_commit: yes
+
+- name: for idempotency, use full-form commands
+  junos_config:
+    lines:
+      # - set int ge-0/0/1 unit 0 desc "Test interface"
+      - set interfaces ge-0/0/1 unit 0 description "Test interface"
 """
 
 RETURN = """

lib/ansible/modules/network/nxos/nxos_config.py

@@ -205,6 +205,9 @@ options:
         argument, the task should also modify the C(diff_against) value and
         set it to I(intended).
     version_added: "2.4"
+notes:
+  - Abbreviated commands are NOT idempotent, see
+    L(Network FAQ,../network/user_guide/faq.html#why-do-the-config-modules-always-return-changed-true-with-abbreviated-commands).
 """
 
 EXAMPLES = """
@@ -245,6 +248,13 @@ EXAMPLES = """
     replace_src: config.txt
     replace: config
 
+- name: for idempotency, use full-form commands
+  nxos_config:
+    lines:
+      # - shut
+      - shutdown
+    # parents: int eth1/1
+    parents: interface Ethernet1/1
 """
 
 RETURN = """

lib/ansible/modules/network/vyos/vyos_config.py

@@ -36,6 +36,8 @@ description:
 extends_documentation_fragment: vyos
 notes:
   - Tested against VYOS 1.1.7
+  - Abbreviated commands are NOT idempotent, see
+    L(Network FAQ,../network/user_guide/faq.html#why-do-the-config-modules-always-return-changed-true-with-abbreviated-commands).
 options:
   lines:
     description:
@@ -102,6 +104,12 @@ EXAMPLES = """
   vyos_config:
     src: vyos.cfg
     backup: yes
+
+- name: for idempotency, use full-form commands
+  vyos_config:
+    lines:
+      # - set int eth eth2 description 'OUTSIDE'
+      - set interface ethernet eth2 description 'OUTSIDE'
 """
 
 RETURN = """