Panos/doc fragment (#37696)

* Create PanOS module documentation fragment

- Module documentation fragment currently holds 3 parameters
- It most likely won't be used in every single module since there is
some variance

* Modified PanOS module for use doc_frags

- Where documentation is consistent, module documentation now uses a
documentation fragment instead of all documentation being contained in
the module.

* Formatting and syntax error fixes

Updated some formatting errors to make ansibot happy.

* Revisions for grammar

lib/ansible/modules/network/panos/panos_admin.py

@@ -36,18 +36,6 @@ version_added: "2.3"
 requirements:
     - pan-python
 options:
-    ip_address:
-        description:
-            - IP address (or hostname) of PAN-OS device
-        required: true
-    password:
-        description:
-            - password for authentication
-        required: true
-    username:
-        description:
-            - username for authentication
-        default: "admin"
     admin_username:
         description:
             - username for admin user
@@ -64,6 +52,7 @@ options:
             - commit if changed
         type: bool
         default: 'yes'
+extends_documentation_fragment: panos
 '''
 
 EXAMPLES = '''

lib/ansible/modules/network/panos/panos_check.py

@@ -31,19 +31,6 @@ version_added: "2.3"
 requirements:
     - pan-python
 options:
-    ip_address:
-        description:
-            - IP address (or hostname) of PAN-OS device
-        required: true
-    password:
-        description:
-            - password for authentication
-        required: true
-    username:
-        description:
-            - username for authentication
-        required: false
-        default: "admin"
     timeout:
         description:
             - timeout of API calls
@@ -54,6 +41,7 @@ options:
             - time waited between checks
         required: false
         default: "0"
+extends_documentation_fragment: panos
 '''
 
 EXAMPLES = '''

lib/ansible/modules/network/panos/panos_commit.py

@@ -31,18 +31,6 @@ version_added: "2.3"
 requirements:
     - pan-python
 options:
-    ip_address:
-        description:
-            - IP address (or hostname) of PAN-OS device
-        required: true
-    password:
-        description:
-            - password for authentication
-        required: true
-    username:
-        description:
-            - username for authentication
-        default: "admin"
     interval:
         description:
             - interval for checking commit job
@@ -55,6 +43,7 @@ options:
             - if commit should be synchronous
         type: bool
         default: 'yes'
+extends_documentation_fragment: panos
 '''
 
 EXAMPLES = '''

lib/ansible/modules/network/panos/panos_dag.py

@@ -30,18 +30,6 @@ version_added: "2.3"
 requirements:
     - pan-python
 options:
-    ip_address:
-        description:
-            - IP address (or hostname) of PAN-OS device
-        required: true
-    password:
-        description:
-            - password for authentication
-        required: true
-    username:
-        description:
-            - username for authentication
-        default: "admin"
     dag_name:
         description:
             - name of the dynamic address group
@@ -55,6 +43,7 @@ options:
             - commit if changed
         type: bool
         default: 'yes'
+extends_documentation_fragment: panos
 '''
 
 EXAMPLES = '''

lib/ansible/modules/network/panos/panos_dag_tags.py

@@ -39,21 +39,9 @@ notes:
     - Checkmode is not supported.
     - Panorama is not supported.
 options:
-    ip_address:
-        description:
-            - IP address (or hostname) of PAN-OS device
-        required: true
-    password:
-        description:
-            - password for authentication
-        required: true
     api_key:
         description:
             - API key that can be used instead of I(username)/I(password) credentials.
-    username:
-        description:
-            - username for authentication
-        default: "admin"
     description:
         description:
             - The purpose / objective of the static Address Group
@@ -74,6 +62,7 @@ options:
     ip_to_register:
         description:
             - IP that will be registered with the given tag names.
+extends_documentation_fragment: panos
 '''
 
 EXAMPLES = '''

lib/ansible/modules/network/panos/panos_import.py

@@ -35,18 +35,6 @@ requirements:
     - requests
     - requests_toolbelt
 options:
-    ip_address:
-        description:
-            - IP address (or hostname) of PAN-OS device.
-        required: true
-    password:
-        description:
-            - Password for device authentication.
-        required: true
-    username:
-        description:
-            - Username for device authentication.
-        default: "admin"
     category:
         description:
             - Category of file uploaded. The default is software.
@@ -64,6 +52,7 @@ options:
         default: yes
         type: bool
         version_added: "2.6"
+extends_documentation_fragment: panos
 '''
 
 EXAMPLES = '''

lib/ansible/modules/network/panos/panos_interface.py

@@ -37,18 +37,6 @@ requirements:
 notes:
     - Checkmode is not supported.
 options:
-    ip_address:
-        description:
-            - IP address (or hostname) of PAN-OS device being configured.
-        required: true
-    username:
-        description:
-            - Username credentials to use for auth.
-        default: "admin"
-    password:
-        description:
-            - Password credentials to use for auth.
-        required: true
     if_name:
         description:
             - Name of the interface to configure.
@@ -66,6 +54,7 @@ options:
         description:
             - Commit if changed
         default: true
+extends_documentation_fragment: panos
 '''
 
 EXAMPLES = '''

lib/ansible/modules/network/panos/panos_lic.py

@@ -32,19 +32,6 @@ version_added: "2.3"
 requirements:
     - pan-python
 options:
-    ip_address:
-        description:
-            - IP address (or hostname) of PAN-OS device
-        required: true
-    password:
-        description:
-            - password for authentication
-        required: true
-    username:
-        description:
-            - username for authentication
-        required: false
-        default: "admin"
     auth_code:
         description:
             - authcode to be applied
@@ -54,6 +41,7 @@ options:
             - whether to apply authcode even if device is already licensed
         required: false
         default: "false"
+extends_documentation_fragment: panos
 '''
 
 EXAMPLES = '''

lib/ansible/modules/network/panos/panos_loadcfg.py

@@ -30,18 +30,6 @@ version_added: "2.3"
 requirements:
     - pan-python
 options:
-    ip_address:
-        description:
-            - IP address (or hostname) of PAN-OS device
-        required: true
-    password:
-        description:
-            - password for authentication
-        required: true
-    username:
-        description:
-            - username for authentication
-        default: "admin"
     file:
         description:
             - configuration file to load
@@ -50,6 +38,7 @@ options:
             - commit if changed
         type: bool
         default: 'yes'
+extends_documentation_fragment: panos
 '''
 
 EXAMPLES = '''

lib/ansible/modules/network/panos/panos_mgtconfig.py

@@ -30,18 +30,6 @@ version_added: "2.3"
 requirements:
     - pan-python
 options:
-    ip_address:
-        description:
-            - IP address (or hostname) of PAN-OS device
-        required: true
-    password:
-        description:
-            - password for authentication
-        required: true
-    username:
-        description:
-            - username for authentication
-        default: "admin"
     dns_server_primary:
         description:
             - address of primary DNS server
@@ -59,6 +47,7 @@ options:
             - commit if changed
         type: bool
         default: 'yes'
+extends_documentation_fragment: panos
 '''
 
 EXAMPLES = '''

lib/ansible/modules/network/panos/panos_pg.py

@@ -30,18 +30,6 @@ version_added: "2.3"
 requirements:
     - pan-python
 options:
-    ip_address:
-        description:
-            - IP address (or hostname) of PAN-OS device
-        required: true
-    password:
-        description:
-            - password for authentication
-        required: true
-    username:
-        description:
-            - username for authentication
-        default: "admin"
     pg_name:
         description:
             - name of the security profile group
@@ -72,6 +60,7 @@ options:
             - commit if changed
         type: bool
         default: 'yes'
+extends_documentation_fragment: panos
 '''
 
 EXAMPLES = '''

lib/ansible/modules/network/panos/panos_restart.py

@@ -29,20 +29,7 @@ author: "Luigi Mori (@jtschichold), Ivan Bojer (@ivanbojer)"
 version_added: "2.3"
 requirements:
     - pan-python
-options:
+extends_documentation_fragment: panos
-    ip_address:
-        description:
-            - IP address (or hostname) of PAN-OS device
-        required: true
-    password:
-        description:
-            - password for authentication
-        required: true
-    username:
-        description:
-            - username for authentication
-        required: false
-        default: "admin"
 '''
 
 EXAMPLES = '''

lib/ansible/modules/network/panos/panos_sag.py

@@ -32,18 +32,6 @@ requirements:
     - pandevice can be obtained from PyPi U(https://pypi.python.org/pypi/pandevice)
     - xmltodict can be obtained from PyPi U(https://pypi.python.org/pypi/xmltodict)
 options:
-    ip_address:
-        description:
-            - IP address (or hostname) of PAN-OS device
-        required: true
-    password:
-        description:
-            - password for authentication
-        required: true
-    username:
-        description:
-            - username for authentication
-        default: "admin"
     api_key:
         description:
             - API key that can be used instead of I(username)/I(password) credentials.
@@ -74,6 +62,7 @@ options:
         description:
             - The operation to perform Supported values are I(add)/I(list)/I(delete).
         required: true
+extends_documentation_fragment: panos
 '''
 
 EXAMPLES = '''

lib/ansible/utils/module_docs_fragments/panos.py

@@ -0,0 +1,25 @@
+# -*- coding: utf-8 -*-
+
+# Copyright: (c) 2016, techbizdev <techbizdev@paloaltonetworks.com>
+# Copyright: (c) 2018, Kevin Breit (@kbreit)
+
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
+
+
+class ModuleDocFragment(object):
+    # Standard files documentation fragment
+    DOCUMENTATION = '''
+options:
+    ip_address:
+        description:
+            - IP address (or hostname) of PAN-OS device.
+        required: true
+    password:
+        description:
+            - Password for authentication.
+        required: true
+    username:
+        description:
+            - Username for authentication.
+        default: "admin"
+'''