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
2024-09-14 20:13:21 +02:00 · 2018-05-09 09:13:22 -05:00 · 2018-05-09 09:13:22 -05:00 · c36aa6ae50
commit c36aa6ae50
parent 75304bd121
14 changed files with 38 additions and 160 deletions
--- a/lib/ansible/modules/network/panos/panos_admin.py
+++ b/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 = '''
--- a/lib/ansible/modules/network/panos/panos_check.py
+++ b/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 = '''
--- a/lib/ansible/modules/network/panos/panos_commit.py
+++ b/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 = '''
--- a/lib/ansible/modules/network/panos/panos_dag.py
+++ b/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 = '''
--- a/lib/ansible/modules/network/panos/panos_dag_tags.py
+++ b/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 = '''
--- a/lib/ansible/modules/network/panos/panos_import.py
+++ b/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 = '''
--- a/lib/ansible/modules/network/panos/panos_interface.py
+++ b/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 = '''
--- a/lib/ansible/modules/network/panos/panos_lic.py
+++ b/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 = '''
--- a/lib/ansible/modules/network/panos/panos_loadcfg.py
+++ b/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 = '''
--- a/lib/ansible/modules/network/panos/panos_mgtconfig.py
+++ b/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 = '''
--- a/lib/ansible/modules/network/panos/panos_pg.py
+++ b/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 = '''
--- a/lib/ansible/modules/network/panos/panos_restart.py
+++ b/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:
-    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"
+extends_documentation_fragment: panos
 '''

 EXAMPLES = '''
--- a/lib/ansible/modules/network/panos/panos_sag.py
+++ b/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 = '''
--- a/lib/ansible/utils/module_docs_fragments/panos.py
+++ b/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"
+'''