Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Feature/centralize doc fragments #86

Closed
wants to merge 3 commits into from
Closed

Feature/centralize doc fragments #86

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
0db577f
remove redundant vmware doc fragment
mikemorency Dec 4, 2024
dcfe76d
centralize doc fragments
mikemorency Dec 4, 2024
bb62cc5
move proxy protocol into rest api doc fragment
mikemorency Dec 9, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions changelogs/fragments/86-centralize-doc-fragments.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
---
minor_changes:
- pyvmomi doc fragments - Remove redundant 'vcenter_documentation' fragment. Add proxy protocol documentation to all modules for simplicity. Remove redundant cluster and datastore docs
152 changes: 51 additions & 101 deletions plugins/doc_fragments/vmware.py
View file
Open in desktop
Copy link
Collaborator Author

@mikemorency mikemorency Dec 4, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

this is a frustratingly complex diff from github.

  1. added the note about the requests library
  2. added the proxy_protocol option with an alias to protocol
  3. removed the VCENTER_DOCUMENTATION block

Original file line number Diff line number Diff line change
Expand Up @@ -11,121 +11,71 @@


class ModuleDocFragment(object):
# Parameters for VMware modules
DOCUMENTATION = r'''
# This document fragment serves as a base for all vmware modules. If you are using the REST API SDK in your module,
# you should use the REST_COMPATIBLE_DOCUMENTATION fragment. Otherwise, you can use this BASE_DOCUMENTATION.
# BASE_DOCUMENTATION covers the arg spec provided by the base_argument_spec() function, while
# REST_COMPATIBLE_DOCUMENTATION covers the arg spec provided by the rest_compatible_argument_spec() function
BASE_DOCUMENTATION = r'''
notes:
- All modules require API write access and hence is not supported on a free ESXi license.
- All variables and VMware object names are case sensitive.
- >-
Modules may rely on the 'requests' python library, which does not use the system certificate store by default. You can
specify the certificate store by setting the REQUESTS_CA_BUNDLE environment variable.
Example: 'export REQUESTS_CA_BUNDLE=/path/to/your/ca_bundle.pem'
options:
hostname:
description:
- The hostname or IP address of the vSphere vCenter or ESXi server.
- If the value is not specified in the task, the value of environment variable E(VMWARE_HOST) will be used instead.
type: str
username:
description:
- The username of the vSphere vCenter or ESXi server.
- If the value is not specified in the task, the value of environment variable E(VMWARE_USER) will be used instead.
type: str
aliases: [ admin, user ]
password:
description:
- The password of the vSphere vCenter or ESXi server.
- If the value is not specified in the task, the value of environment variable E(VMWARE_PASSWORD) will be used instead.
type: str
aliases: [ pass, pwd ]
validate_certs:
description:
- Allows connection when SSL certificates are not valid. Set to V(false) when certificates are not trusted.
- If the value is not specified in the task, the value of environment variable E(VMWARE_VALIDATE_CERTS) will be used instead.
type: bool
default: true
port:
description:
- The port number of the vSphere vCenter or ESXi server.
- If the value is not specified in the task, the value of environment variable E(VMWARE_PORT) will be used instead.
type: int
default: 443
datacenter:
description:
- The datacenter to use when connecting to a vCenter.
type: str
aliases: [ datacenter_name ]
cluster:
description:
- The cluster to use when connecting to a vCenter.
type: str
aliases: [ cluster_name ]
proxy_host:
description:
- Address of a proxy that will receive all HTTPS requests and relay them.
- The format is a hostname or a IP.
- If the value is not specified in the task, the value of environment variable E(VMWARE_PROXY_HOST) will be used instead.
type: str
required: false
proxy_port:
description:
- Port of the HTTP proxy that will receive all HTTPS requests and relay them.
- If the value is not specified in the task, the value of environment variable E(VMWARE_PROXY_PORT) will be used instead.
type: int
required: false
'''

# This doc fragment is specific to vcenter modules like vcenter_license
VCENTER_DOCUMENTATION = r'''
notes:
- All modules require API write access and hence is not supported on a free ESXi license.
options:
hostname:
description:
hostname:
description:
- The hostname or IP address of the vSphere vCenter server.
- If the value is not specified in the task, the value of environment variable E(VMWARE_HOST) will be used instead.
type: str
username:
description:
type: str
username:
description:
- The username of the vSphere vCenter server.
- If the value is not specified in the task, the value of environment variable E(VMWARE_USER) will be used instead.
type: str
aliases: [ admin, user ]
password:
description:
type: str
aliases: [ admin, user ]
password:
description:
- The password of the vSphere vCenter server.
- If the value is not specified in the task, the value of environment variable E(VMWARE_PASSWORD) will be used instead.
type: str
aliases: [ pass, pwd ]
validate_certs:
description:
type: str
aliases: [ pass, pwd ]
validate_certs:
description:
- Allows connection when SSL certificates are not valid. Set to V(false) when certificates are not trusted.
- If the value is not specified in the task, the value of environment variable E(VMWARE_VALIDATE_CERTS) will be used instead.
type: bool
default: true
port:
description:
type: bool
default: true
port:
description:
- The port number of the vSphere vCenter server.
- If the value is not specified in the task, the value of environment variable E(VMWARE_PORT) will be used instead.
type: int
default: 443
datacenter:
description:
- The datacenter to use when connecting to a vCenter.
type: str
aliases: [ datacenter_name ]
cluster:
description:
- The cluster to use when connecting to a vCenter.
type: str
aliases: [ cluster_name ]
proxy_host:
description:
type: int
default: 443
proxy_host:
description:
- Address of a proxy that will receive all HTTPS requests and relay them.
- The format is a hostname or a IP.
- If the value is not specified in the task, the value of environment variable E(VMWARE_PROXY_HOST) will be used instead.
type: str
required: false
proxy_port:
description:
- Port of the HTTP proxy that will receive all HTTPS requests and relay them.
- If the value is not specified in the task, the value of environment variable E(VMWARE_PROXY_PORT) will be used instead.
type: int
required: false
'''
type: str
required: false
proxy_port:
description:
- Port of the HTTP proxy that will receive all HTTPS requests and relay them.
- If the value is not specified in the task, the value of environment variable E(VMWARE_PROXY_PORT) will be used instead.
type: int
required: false
'''
# Use this document fragment a base for any vmware modules that use the REST API SDK. If your module uses
# both the REST SDK and pyvmomi, you should still use this doc fragment
REST_COMPATIBLE_DOCUMENTATION = BASE_DOCUMENTATION + r'''
proxy_protocol:
description:
- The proxy connection protocol to use.
- This is option is used if the correct proxy protocol cannot be automatically determined.
type: str
choices: [ http, https ]
default: https
aliases: [protocol]
'''
2 changes: 1 addition & 1 deletion plugins/modules/cluster.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -46,7 +46,7 @@
- module: community.vmware.vmware_cluster_ha
- module: community.vmware.vmware_cluster_vsan
extends_documentation_fragment:
- vmware.vmware.vmware.documentation
- vmware.vmware.vmware.base_documentation
'''

EXAMPLES = r'''
Expand Down
2 changes: 1 addition & 1 deletion plugins/modules/cluster_dpm.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -58,7 +58,7 @@
choices: [ 1, 2, 3, 4, 5 ]

extends_documentation_fragment:
- vmware.vmware.vmware.documentation
- vmware.vmware.vmware.base_documentation
'''

EXAMPLES = r'''
Expand Down
2 changes: 1 addition & 1 deletion plugins/modules/cluster_drs.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -73,7 +73,7 @@
default: false

extends_documentation_fragment:
- vmware.vmware.vmware.documentation
- vmware.vmware.vmware.base_documentation
'''

EXAMPLES = r'''
Expand Down
2 changes: 1 addition & 1 deletion plugins/modules/cluster_drs_recommendations.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -42,7 +42,7 @@
aliases: [ datacenter_name ]

extends_documentation_fragment:
- vmware.vmware.vmware.documentation
- vmware.vmware.vmware.base_documentation
'''

EXAMPLES = r'''
Expand Down
2 changes: 1 addition & 1 deletion plugins/modules/cluster_info.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -57,7 +57,7 @@
elements: str

extends_documentation_fragment:
- vmware.vmware.vmware.vcenter_documentation
- vmware.vmware.vmware.rest_compatible_documentation
'''

EXAMPLES = r'''
Expand Down
2 changes: 1 addition & 1 deletion plugins/modules/cluster_vcls.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -63,7 +63,7 @@


extends_documentation_fragment:
- vmware.vmware.vmware.documentation
- vmware.vmware.vmware.base_documentation
'''

EXAMPLES = r'''
Expand Down
2 changes: 1 addition & 1 deletion plugins/modules/folder_template_from_vm.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -99,7 +99,7 @@
description: The check_mode support.
support: full
extends_documentation_fragment:
- vmware.vmware.vmware.vcenter_documentation
- vmware.vmware.vmware.base_documentation

'''

Expand Down
2 changes: 1 addition & 1 deletion plugins/modules/license_info.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,7 @@
description: The check_mode support.
support: full
extends_documentation_fragment:
- vmware.vmware.vmware.vcenter_documentation
- vmware.vmware.vmware.base_documentation
'''

EXAMPLES = r'''
Expand Down
Loading