Granular K8s doc fragments (#34215)

* Makes doc fragment more granular

* Fix lint issues

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

@@ -32,7 +32,10 @@ description:
   - Supports check mode, and the diff option.
 
 extends_documentation_fragment:
-  - kubernetes
+  - k8s_state_options
+  - k8s_name_options
+  - k8s_resource_options
+  - k8s_auth_options
 
 requirements:
   - "python >= 2.7"

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

@@ -31,7 +31,11 @@ description:
   - Authenticate using either a config file, certificates, password or token.
   - Supports check mode, and the diff option.
 
-extends_documentation_fragment: kubernetes
+extends_documentation_fragment:
+  - k8s_state_options
+  - k8s_name_options
+  - k8s_resource_options
+  - k8s_auth_options
 
 options:
   description:

lib/ansible/utils/module_docs_fragments/k8s_auth_options.py

@@ -0,0 +1,71 @@
+#
+#  Copyright 2018 Red Hat | Ansible
+#
+# This file is part of Ansible
+#
+# Ansible is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# Ansible is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with Ansible.  If not, see <http://www.gnu.org/licenses/>.
+
+# Options for authenticating with the API.
+
+
+class ModuleDocFragment(object):
+
+    DOCUMENTATION = '''
+options:
+  host:
+    description:
+    - Provide a URL for accessing the API. Can also be specified via K8S_AUTH_HOST environment variable.
+  api_key:
+    description:
+    - Token used to authenticate with the API. Can also be specified via K8S_AUTH_API_KEY environment variable.
+  kubeconfig:
+    description:
+    - Path to an existing Kubernetes config file. If not provided, and no other connection
+      options are provided, the openshift client will attempt to load the default
+      configuration file from I(~/.kube/config.json). Can also be specified via K8S_AUTH_KUBECONFIG environment
+      variable.
+  context:
+    description:
+    - The name of a context found in the config file. Can also be specified via K8S_AUTH_CONTEXT environment variable.
+  username:
+    description:
+    - Provide a username for authenticating with the API. Can also be specified via K8S_AUTH_USERNAME environment
+      variable.
+  password:
+    description:
+    - Provide a password for authenticating with the API. Can also be specified via K8S_AUTH_PASSWORD environment
+      variable.
+  cert_file:
+    description:
+    - Path to a certificate used to authenticate with the API. Can also be specified via K8S_AUTH_CERT_FILE environment
+      variable.
+  key_file:
+    description:
+    - Path to a key file used to authenticate with the API. Can also be specified via K8S_AUTH_HOST environment
+      variable.
+  ssl_ca_cert:
+    description:
+    - Path to a CA certificate used to authenticate with the API. Can also be specified via K8S_AUTH_SSL_CA_CERT
+      environment variable.
+  verify_ssl:
+    description:
+    - "Whether or not to verify the API server's SSL certificates. Can also be specified via K8S_AUTH_VERIFY_SSL
+      environment variable."
+    type: bool
+
+notes:
+  - "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"
+'''

lib/ansible/utils/module_docs_fragments/k8s_name_options.py

@@ -0,0 +1,54 @@
+#
+#  Copyright 2018 Red Hat | Ansible
+#
+# This file is part of Ansible
+#
+# Ansible is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# Ansible is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with Ansible.  If not, see <http://www.gnu.org/licenses/>.
+
+# Options for selecting or identifying a specific K8s object
+
+
+class ModuleDocFragment(object):
+
+    DOCUMENTATION = '''
+options:
+  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
+  kind:
+    description:
+    - Use to specify an object model. Use to create, delete, or discover an object without providing a full
+      resource definition. Use in conjunction with I(api_version), I(name), and I(namespace) to identify a
+      specific object. If I(resource definition) is provided, the I(kind) from the I(resource_definition)
+      will override this option.
+  name:
+    description:
+    - Use to specify an object name. Use to create, delete, or discover an object without providing a full
+      resource definition. Use in conjunction with I(api_version), I(kind) and I(namespace) to identify a
+      specific object. If I(resource definition) is provided, the I(metadata.name) value from the
+      I(resource_definition) will override this option.
+  namespace:
+    description:
+    - Use to specify an object namespace. Useful when creating, deleting, or discovering an object without
+      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.
+'''

lib/ansible/utils/module_docs_fragments/k8s_resource_options.py

@@ -0,0 +1,41 @@
+#
+#  Copyright 2018 Red Hat | Ansible
+#
+# This file is part of Ansible
+#
+# Ansible is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# Ansible is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with Ansible.  If not, see <http://www.gnu.org/licenses/>.
+
+# Options for providing an object configuration
+
+
+class ModuleDocFragment(object):
+
+    DOCUMENTATION = '''
+options:
+  resource_definition:
+    description:
+    - "Provide a valid YAML definition for an object when creating or updating. NOTE: I(kind), I(api_version), I(name),
+      and I(namespace) will be overwritten by corresponding values found in the provided I(resource_definition)."
+    aliases:
+    - definition
+    - inline
+  src:
+    description:
+    - "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.
+'''

lib/ansible/utils/module_docs_fragments/k8s_state_options.py

@@ -0,0 +1,41 @@
+#
+#  Copyright 2018 Red Hat | Ansible
+#
+# This file is part of Ansible
+#
+# Ansible is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# Ansible is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with Ansible.  If not, see <http://www.gnu.org/licenses/>.
+
+# Options for specifying object state
+
+
+class ModuleDocFragment(object):
+
+    DOCUMENTATION = '''
+options:
+  state:
+    description:
+    - Determines if an object should be created, patched, or deleted. When set to C(present), an object will be
+      created, if it does not already exist. If set to C(absent), an existing object will be deleted. If set to
+      C(present), an existing object will be patched, if its attributes differ from those specified using
+      I(resource_definition) or I(src).
+    default: present
+    choices:
+    - present
+    - absent
+  force:
+    description:
+    - If set to C(True), and I(state) is C(present), an existing object will be replaced.
+    default: false
+    type: bool
+'''

lib/ansible/utils/module_docs_fragments/kubernetes.py

@@ -1,125 +0,0 @@
-# This file is part of Ansible
-#
-# Ansible is free software: you can redistribute it and/or modify
-# it under the terms of the GNU General Public License as published by
-# the Free Software Foundation, either version 3 of the License, or
-# (at your option) any later version.
-#
-# Ansible is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU General Public License for more details.
-#
-# You should have received a copy of the GNU General Public License
-# along with Ansible.  If not, see <http://www.gnu.org/licenses/>.
-#
-
-
-class ModuleDocFragment(object):
-
-    DOCUMENTATION = '''
-options:
-  state:
-    description:
-    - Determines if an object should be created, patched, or deleted. When set to C(present), an object will be
-      created, if it does not already exist. If set to C(absent), an existing object will be deleted. If set to
-      C(present), an existing object will be patched, if its attributes differ from those specified using
-      I(resource_definition) or I(src).
-    default: present
-    choices:
-    - present
-    - absent
-  force:
-    description:
-    - If set to C(True), and I(state) is C(present), an existing object will be replaced.
-    default: false
-    type: bool
-  resource_definition:
-    description:
-    - "Provide a valid YAML definition for an object when creating or updating. NOTE: I(kind), I(api_version), I(name),
-      and I(namespace) will be overwritten by corresponding values found in the provided I(resource_definition)."
-    aliases:
-    - definition
-    - inline
-  src:
-    description:
-    - "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
-  kind:
-    description:
-    - Use to specify an object model. Use to create, delete, or discover an object without providing a full
-      resource definition. Use in conjunction with I(api_version), I(name), and I(namespace) to identify a
-      specific object. If I(resource definition) is provided, the I(kind) from the I(resource_definition)
-      will override this option.
-  name:
-    description:
-    - Use to specify an object name. Use to create, delete, or discover an object without providing a full
-      resource definition. Use in conjunction with I(api_version), I(kind) and I(namespace) to identify a
-      specific object. If I(resource definition) is provided, the I(metadata.name) value from the
-      I(resource_definition) will override this option.
-  namespace:
-    description:
-    - Use to specify an object namespace. Useful when creating, deleting, or discovering an object without
-      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.
-  host:
-    description:
-    - Provide a URL for accessing the API. Can also be specified via K8S_AUTH_HOST environment variable.
-  api_key:
-    description:
-    - Token used to authenticate with the API. Can also be specified via K8S_AUTH_API_KEY environment variable.
-  kubeconfig:
-    description:
-    - Path to an existing Kubernetes config file. If not provided, and no other connection
-      options are provided, the openshift client will attempt to load the default
-      configuration file from I(~/.kube/config.json). Can also be specified via K8S_AUTH_KUBECONFIG environment
-      variable.
-  context:
-    description:
-    - The name of a context found in the config file. Can also be specified via K8S_AUTH_CONTEXT environment variable.
-  username:
-    description:
-    - Provide a username for authenticating with the API. Can also be specified via K8S_AUTH_USERNAME environment
-      variable.
-  password:
-    description:
-    - Provide a password for authenticating with the API. Can also be specified via K8S_AUTH_PASSWORD environment
-      variable.
-  cert_file:
-    description:
-    - Path to a certificate used to authenticate with the API. Can also be specified via K8S_AUTH_CERT_FILE environment
-      variable.
-  key_file:
-    description:
-    - Path to a key file used to authenticate with the API. Can also be specified via K8S_AUTH_HOST environment
-      variable.
-  ssl_ca_cert:
-    description:
-    - Path to a CA certificate used to authenticate with the API. Can also be specified via K8S_AUTH_SSL_CA_CERT
-      environment variable.
-  verify_ssl:
-    description:
-    - "Whether or not to verify the API server's SSL certificates. Can also be specified via K8S_AUTH_VERIFY_SSL
-      environment variable."
-    type: bool
-
-notes:
-  - "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"
-'''