Improving docs and examples (#34155)

* Improving docs and examples

* Removes trailing whitespace

lib/ansible/module_utils/k8s_common.py

@@ -77,7 +77,8 @@ ARG_SPEC = {
     'description': {},
     'display_name': {},
     'api_version': {
-        'aliases': ['api', 'version']
+        'default': 'v1',
+        'aliases': ['api', 'version'],
     },
     'kubeconfig': {
         'type': 'path',

lib/ansible/modules/clustering/k8s/k8s_raw.py

@@ -24,16 +24,20 @@ version_added: "2.5"
 author: "Chris Houseknecht (@chouseknecht)"
 
 description:
-  - Use the OpenShift Python client to perform CRUD operations on Kubernetes objects.
-  - Supports authentication using either a config file, certificates, password or token.
+  - Use the OpenShift Python client to perform CRUD operations on K8s objects.
+  - Pass the object definition from a source file or inline. See examples for reading
+    files and using Jinja templates.
+  - Access to the full range of K8s APIs.
+  - Authenticate using either a config file, certificates, password or token.
+  - Supports check mode, and the diff option.
 
 extends_documentation_fragment:
   - kubernetes
 
 requirements:
-    - "python >= 2.7"
-    - "openshift >= 0.3"
-    - "PyYAML >= 3.11"
+  - "python >= 2.7"
+  - "openshift >= 0.3"
+  - "PyYAML >= 3.11"
 '''
 
 EXAMPLES = '''
@@ -93,6 +97,23 @@ EXAMPLES = '''
     kind: Service
     namespace: testing
     name: web
+
+# Passing the object definition from a file
+
+- name: Create a Deployment by reading the definition from a local file
+  k8s_raw:
+    state: present
+    src: /testing/deployment.yml
+
+- name: Read definition file from the Ansible controller file system
+  k8s_raw:
+    state: present
+    definition: "{{ lookup('file', '/testing/deployment.yml') | from_yaml }}"
+
+- name: Read definition file from the Ansible controller file system after Jinja templating
+  k8s_raw:
+    state: present
+    definition: "{{ lookup('template', '/testing/deployment.yml') | from_yaml }}"
 '''
 
 RETURN = '''

lib/ansible/modules/clustering/openshift/openshift_raw.py

@@ -25,10 +25,24 @@ author: "Chris Houseknecht (@chouseknecht)"
 
 description:
   - Use the OpenShift Python client to perform CRUD operations on OpenShift objects.
-  - Supports authentication using either a config file, certificates, password or token.
+  - Pass the object definition from a source file or inline. See examples for reading
+    files and using Jinja templates.
+  - Access to the full range of K8s and OpenShift APIs.
+  - Authenticate using either a config file, certificates, password or token.
+  - Supports check mode, and the diff option.
 
 extends_documentation_fragment: kubernetes
 
+options:
+  description:
+    description:
+    - Use only when creating a project, otherwise ignored. Adds a description to the project
+      metadata.
+  display_name:
+    description:
+    - Use only when creating a project, otherwise ignored. Adds a display name to the project
+      metadata.
+
 requirements:
     - "python >= 2.7"
     - "openshift >= 0.3"
@@ -95,18 +109,6 @@ EXAMPLES = '''
           strategy:
             type: Rolling
 
-- name: Create a Deployment by reading the definition from a file
-  openshift_raw:
-    state: present
-    src: /testing/deployment.yml
-
-- name: Get the list of all Deployments
-  openshift_raw:
-    api_version: v1
-    kind: DeploymentConfigList
-    namespace: testing
-  register: deployment_list
-
 - name: Remove an existing Deployment
   openshift_raw:
     api_version: v1
@@ -117,7 +119,7 @@ EXAMPLES = '''
 
 - name: Create a Secret
   openshift_raw:
-    inline:
+    definition:
       apiVersion: v1
       kind: Secret
       metadata:
@@ -128,13 +130,30 @@ EXAMPLES = '''
         username: "{{ 'admin' | b64encode }}"
         password: "{{ 'foobard' | b64encode }}"
 
-- name: Retrieve the Secret
+- name: Retrieve a Secret
   openshift_raw:
     api: v1
     kind: Secret
     name: mysecret
     namespace: testing
   register: mysecret
+
+# Passing the object definition from a file
+
+- name: Create a Deployment by reading the definition from a local file
+  openshift_raw:
+    state: present
+    src: /testing/deployment.yml
+
+- name: Read definition file from the Ansible controller file system
+  openshift_raw:
+    state: present
+    definition: "{{ lookup('file', '/testing/deployment.yml') | from_yaml }}"
+
+- name: Read definition file from the Ansible controller file system after Jinja templating
+  openshift_raw:
+    state: present
+    definition: "{{ lookup('template', '/testing/deployment.yml') | from_yaml }}"
 '''
 
 RETURN = '''

lib/ansible/utils/module_docs_fragments/kubernetes.py

@@ -46,12 +46,16 @@ options:
     - "Provide a path to a file containing a valid YAML definition of an object to be created or updated. Mutually
       exclusive with I(resource_definition). NOTE: I(kind), I(api_version), I(name), and I(namespace) will be
       overwritten by corresponding values found in the configuration read in from the I(src) file."
+    - Reads from the local file system. To read from the Ansible controller's file system, use the file lookup
+      plugin or template lookup plugin, combined with the from_yaml filter, and pass the result to
+      I(resource_definition). See Examples below.
   api_version:
     description:
     - Use to specify the API version. Use to create, delete, or discover an object without providing a full
       resource definition. Use in conjunction with I(kind), I(name), and I(namespace) to identify a
       specific object. If I(resource definition) is provided, the I(apiVersion) from the I(resource_definition)
       will override this option.
+    default: v1
     aliases:
     - api
     - version
@@ -73,14 +77,6 @@ options:
       providing a full resource definition. Use in conjunction with I(api_version), I(kind), and I(name)
       to identify a specfic object. If I(resource definition) is provided, the I(metadata.namespace) value
       from the I(resource_definition) will override this option.
-  description:
-    description:
-    - Used only when creating an OpenShift project, otherwise ignored. Adds a description to the project meta
-      data.
-  display_name:
-    description:
-    - Use only when creating an OpenShift project, otherwise ignored. Adds a display name to the project meta
-      data.
   host:
     description:
     - Provide a URL for accessing the API. Can also be specified via K8S_AUTH_HOST environment variable.
@@ -123,6 +119,7 @@ options:
     type: bool
 
 notes:
-  - "To learn more about the OpenShift Python client and available object models, visit:
-    https://github.com/openshift/openshift-restclient-python"
+  - "The OpenShift Python client wraps the K8s Python client, providing full access to
+    all of the APIS and models available on both platforms. For API version details and
+    additional information visit https://github.com/openshift/openshift-restclient-python"
 '''