internet/community.general
3
0
Fork 0
mirror of https://github.com/ansible-collections/community.general.git synced 2026-05-08 14:22:46 +00:00
Code Issues Packages Projects Releases Wiki Activity

Clean up module documentation (#36909)

Browse Source 
* Clean up module documentation

This PR includes:
- Removal of `default: None` (and variations)
- Removal of `required: false`
- Fixing booleans and `type: bool` where required

* Fix remaining (new) validation issues
This commit is contained in:
Dag Wieers
2018-03-15 22:15:24 +01:00
committed by GitHub
parent 58eb2e849d
commit cdd21e2170
624 changed files with 1458 additions and 9114 deletions
Download Patch File Download Diff File Expand all files Collapse all files

41
lib/ansible/modules/web_infrastructure/ansible_tower/tower_credential.py
View File

@@ -33,23 +33,15 @@ options:
user:
description:
- User that should own this credential.
required: False
default: null
team:
description:
- Team that should own this credential.
required: False
default: null
project:
description:
- Project that should for this credential.
required: False
default: null
organization:
description:
- Organization that should own the credential.
required: False
default: null
kind:
description:
- Type of credential being added.
@@ -58,86 +50,59 @@ options:
host:
description:
- Host for this credential.
required: False
default: null
username:
description:
- Username for this credential. access_key for AWS.
required: False
default: null
password:
description:
- Password for this credential. Use ASK for prompting. secret_key for AWS. api_key for RAX.
required: False
default: null
ssh_key_data:
description:
- Path to SSH private key.
required: False
default: null
ssh_key_unlock:
description:
- Unlock password for ssh_key. Use ASK for prompting.
authorize:
description:
- Should use authorize for net type.
required: False
default: False
type: bool
default: 'no'
authorize_password:
description:
- Password for net credentials that require authorize.
required: False
default: null
client:
description:
- Client or application ID for azure_rm type.
required: False
default: null
secret:
description:
- Secret token for azure_rm type.
required: False
default: null
subscription:
description:
- Subscription ID for azure_rm type.
required: False
default: null
tenant:
description:
- Tenant ID for azure_rm type.
required: False
default: null
domain:
description:
- Domain for openstack type.
required: False
default: null
become_method:
description:
- Become method to Use for privledge escalation.
required: False
choices: ["None", "sudo", "su", "pbrun", "pfexec", "pmrun"]
default: "None"
become_username:
description:
- Become username. Use ASK for prompting.
required: False
default: null
become_password:
description:
- Become password. Use ASK for prompting.
required: False
default: null
vault_password:
description:
- Valut password. Use ASK for prompting.
state:
description:
- Desired state of the resource.
required: False
default: "present"
choices: ["present", "absent"]
default: "present"
extends_documentation_fragment: tower
'''

29
lib/ansible/modules/web_infrastructure/ansible_tower/tower_group.py
View File

@@ -30,8 +30,6 @@ options:
description:
description:
- The description to use for the group.
required: False
default: null
inventory:
description:
- Inventory the group should be made a member of.
@@ -39,63 +37,44 @@ options:
variables:
description:
- Variables to use for the group, use C(@) for a file.
required: False
default: null
credential:
description:
- Credential to use for the group.
required: False
default: null
source:
description:
- The source to use for this group.
required: False
default: null,
choices: ["manual", "file", "ec2", "rax", "vmware", "gce", "azure", "azure_rm", "openstack", "satellite6" , "cloudforms", "custom"]
source_regions:
description:
- Regions for cloud provider.
required: False
default: null
source_vars:
description:
- Override variables from source with variables from this field.
required: False
default: null
instance_filters:
description:
- Comma-separated list of filter expressions for matching hosts.
required: False
default: null
group_by:
description:
- Limit groups automatically created from inventory source.
required: False
default: null
source_script:
description:
- Inventory script to be used when group type is C(custom).
required: False
default: null
overwrite:
description:
- Delete child groups and hosts not found in source.
required: False
default: False
type: bool
default: 'no'
overwrite_vars:
description:
- Override vars in child groups and hosts with those from external source.
required: False
default: null
update_on_launch:
description:
- Refresh inventory data from its source each time a job is run.
required: False
default: False
type: bool
default: 'no'
state:
description:
- Desired state of the resource.
required: False
default: "present"
choices: ["present", "absent"]
extends_documentation_fragment: tower

9
lib/ansible/modules/web_infrastructure/ansible_tower/tower_host.py
View File

@@ -30,8 +30,6 @@ options:
description:
description:
- The description to use for the host.
required: False
default: null
inventory:
description:
- Inventory the host should be made a member of.
@@ -39,17 +37,16 @@ options:
enabled:
description:
- If the host should be enabled.
required: False
default: True
type: bool
default: 'yes'
variables:
description:
- Variables to use for the host. Use C(@) for a file.
state:
description:
- Desired state of the resource.
required: False
default: "present"
choices: ["present", "absent"]
default: "present"
extends_documentation_fragment: tower
'''

5
lib/ansible/modules/web_infrastructure/ansible_tower/tower_inventory.py
View File

@@ -30,8 +30,6 @@ options:
description:
description:
- The description to use for the inventory.
required: False
default: null
organization:
description:
- Organization the inventory belongs to.
@@ -39,12 +37,9 @@ options:
variables:
description:
- Inventory variables. Use C(@) to get from file.
required: False
default: null
state:
description:
- Desired state of the resource.
required: False
default: "present"
choices: ["present", "absent"]
extends_documentation_fragment: tower

10
lib/ansible/modules/web_infrastructure/ansible_tower/tower_job_launch.py
View File

@@ -30,36 +30,30 @@ options:
job_explanation:
description:
- Job explanation field.
default: null
job_type:
description:
- Job_type to use for the job, only used if prompt for job_type is set.
choices: ["run", "check", "scan"]
default: null
inventory:
description:
- Inventory to use for the job, only used if prompt for inventory is set.
default: null
credential:
description:
- Credential to use for job, only used if prompt for credential is set.
default: null
extra_vars:
description:
- Extra_vars to use for the job_template. Prepend C(@) if a file.
default: null
limit:
description:
- Limit to use for the I(job_template).
default: null
tags:
description:
- Specific tags to use for from playbook.
default: null
use_job_endpoint:
description:
- Disable launching jobs from job template.
default: False
type: bool
default: 'no'
extends_documentation_fragment: tower
'''

6
lib/ansible/modules/web_infrastructure/ansible_tower/tower_job_list.py
View File

@@ -26,20 +26,18 @@ options:
status:
description:
- Only list jobs with this status.
default: null
choices: ['pending', 'waiting', 'running', 'error', 'failed', 'canceled', 'successful']
page:
description:
- Page number of the results to fetch.
default: null
all_pages:
description:
- Fetch all the pages and return a single result.
default: False
type: bool
default: 'no'
query:
description:
- Query used to further filter the list of jobs. C({"foo":"bar"}) will be passed at C(?foo=bar)
default: null
extends_documentation_fragment: tower
'''

49
lib/ansible/modules/web_infrastructure/ansible_tower/tower_job_template.py
View File

@@ -30,8 +30,6 @@ options:
description:
description:
- Description to use for the job template.
required: False
default: null
job_type:
description:
- The job_type to use for the job template.
@@ -40,8 +38,6 @@ options:
inventory:
description:
- Inventory to use for the job template.
required: False
default: null
project:
description:
- Project to use for the job template.
@@ -53,88 +49,67 @@ options:
machine_credential:
description:
- Machine_credential to use for the job template.
required: False
default: null
cloud_credential:
description:
- Cloud_credential to use for the job template.
required: False
default: null
network_credential:
description:
- The network_credential to use for the job template.
required: False
default: null
forks:
description:
- The number of parallel or simultaneous processes to use while executing the playbook.
required: False
default: null
limit:
description:
- A host pattern to further constrain the list of hosts managed or affected by the playbook
required: False
default: null
verbosity:
description:
- Control the output level Ansible produces as the playbook runs.
required: False
choices: ["verbose", "debug"]
default: null
job_tags:
description:
- The job_tags to use for the job template.
required: False
default: null
skip_tags:
description:
- The skip_tags to use for the job template.
required: False
default: null
host_config_key:
description:
- Allow provisioning callbacks using this host config key.
required: False
default: null
extra_vars_path:
description:
- Path to the C(extra_vars) YAML file.
required: False
default: null
ask_extra_vars:
description:
- Prompt user for C(extra_vars) on launch.
required: False
default: False
type: bool
default: 'no'
ask_tags:
description:
- Prompt user for job tags on launch.
required: False
default: False
type: bool
default: 'no'
ask_job_type:
description:
- Prompt user for job type on launch.
required: False
default: False
type: bool
default: 'no'
ask_inventory:
description:
- Propmt user for inventory on launch.
required: False
default: False
type: bool
default: 'no'
ask_credential:
description:
- Prompt user for credential on launch.
required: False
default: False
type: bool
default: 'no'
become_enabled:
description:
- Activate privilege escalation.
required: False
default: False
type: bool
default: 'no'
state:
description:
- Desired state of the resource.
required: False
default: "present"
choices: ["present", "absent"]
extends_documentation_fragment: tower

1
lib/ansible/modules/web_infrastructure/ansible_tower/tower_job_wait.py
View File

@@ -38,7 +38,6 @@ options:
timeout:
description:
- Maximum time in seconds to wait for a job to finish.
default: null
extends_documentation_fragment: tower
'''

3
lib/ansible/modules/web_infrastructure/ansible_tower/tower_label.py
View File

@@ -27,16 +27,13 @@ options:
description:
- Name to use for the label.
required: True
default: null
organization:
description:
- Organization the label should be applied to.
required: True
default: null
state:
description:
- Desired state of the resource.
required: False
default: "present"
choices: ["present", "absent"]
extends_documentation_fragment: tower

3
lib/ansible/modules/web_infrastructure/ansible_tower/tower_organization.py
View File

@@ -30,12 +30,9 @@ options:
description:
description:
- The description to use for the organization.
required: False
default: null
state:
description:
- Desired state of the resource.
required: False
default: "present"
choices: ["present", "absent"]
extends_documentation_fragment: tower

29
lib/ansible/modules/web_infrastructure/ansible_tower/tower_project.py
View File

@@ -27,62 +27,47 @@ options:
description:
- Name to use for the project.
required: True
default: null
description:
description:
- Description to use for the project.
required: False
default: null
scm_type:
description:
- Type of SCM resource.
required: False
default: "manual"
choices: ["manual", "git", "hg", "svn"]
default: "manual"
scm_url:
description:
- URL of SCM resource.
required: False
default: null
local_path:
description:
- The server playbook directory for manual projects.
required: False
default: null
scm_branch:
description:
- The branch to use for the SCM resource.
required: False
default: null
scm_credential:
description:
- Name of the credential to use with this SCM resource.
required: False
default: null
scm_clean:
description:
- Remove local modifications before updating.
required: False
default: False
type: bool
default: 'no'
scm_delete_on_update:
description:
- Remove the repository completely before updating.
required: False
default: False
type: bool
default: 'no'
scm_update_on_launch:
description:
- Before an update to the local repository before launching a job with this project.
required: False
default: False
type: bool
default: 'no'
organization:
description:
- Primary key of organization for project.
required: False
default: null
state:
description:
- Desired state of the resource.
required: False
default: "present"
choices: ["present", "absent"]
extends_documentation_fragment: tower

17
lib/ansible/modules/web_infrastructure/ansible_tower/tower_role.py
View File

@@ -26,13 +26,9 @@ options:
user:
description:
- User that receives the permissions specified by the role.
required: False
default: null
team:
description:
- Team that receives the permissions specified by the role.
required: False
default: null
role:
description:
- The role type to grant/revoke.
@@ -41,37 +37,24 @@ options:
target_team:
description:
- Team that the role acts on.
required: False
default: null
inventory:
description:
- Inventory the role acts on.
required: False
default: null
job_template:
description:
- The job template the role acts on.
required: False
default: null
credential:
description:
- Credential the role acts on.
required: False
default: null
organization:
description:
- Organization the role acts on.
required: False
default: null
project:
description:
- Project the role acts on.
required: False
default: null
state:
description:
- Desired state of the resource.
required: False
default: "present"
choices: ["present", "absent"]
extends_documentation_fragment: tower

5
lib/ansible/modules/web_infrastructure/ansible_tower/tower_team.py
View File

@@ -27,18 +27,15 @@ options:
description:
- Name to use for the team.
required: True
default: null
organization:
description:
- Organization the team should be made a member of.
required: True
default: null
state:
description:
- Desired state of the resource.
required: False
default: "present"
choices: ["present", "absent"]
default: "present"
extends_documentation_fragment: tower
'''

15
lib/ansible/modules/web_infrastructure/ansible_tower/tower_user.py
View File

@@ -30,13 +30,9 @@ options:
first_name:
description:
- First name of the user.
required: False
default: null
last_name:
description:
- Last name of the user.
required: False
default: null
email:
description:
- Email address of the user.
@@ -44,22 +40,19 @@ options:
password:
description:
- Password of the user.
required: False
default: null
superuser:
description:
- User is a system wide administator.
required: False
default: False
type: bool
default: 'no'
auditor:
description:
- User is a system wide auditor.
required: False
default: False
type: bool
default: 'no'
state:
description:
- Desired state of the resource.
required: False
default: "present"
choices: ["present", "absent"]
extends_documentation_fragment: tower

16
lib/ansible/modules/web_infrastructure/apache2_mod_proxy.py
View File

@@ -27,42 +27,36 @@ description:
python module.
options:
balancer_url_suffix:
default: /balancer-manager/
description:
- Suffix of the balancer pool url required to access the balancer pool
status page (e.g. balancer_vhost[:port]/balancer_url_suffix).
required: false
default: /balancer-manager/
balancer_vhost:
default: None
description:
- (ipv4|ipv6|fqdn):port of the Apache httpd 2.4 mod_proxy balancer pool.
required: true
member_host:
default: None
description:
- (ipv4|ipv6|fqdn) of the balancer member to get or to set attributes to.
Port number is autodetected and should not be specified here.
If undefined, apache2_mod_proxy module will return a members list of
dictionaries of all the current balancer pool members' attributes.
required: false
state:
default: None
description:
- Desired state of the member host.
(absent|disabled),drained,hot_standby,ignore_errors can be
simultaneously invoked by separating them with a comma (e.g. state=drained,ignore_errors).
required: false
choices: ["present", "absent", "enabled", "disabled", "drained", "hot_standby", "ignore_errors"]
tls:
default: false
description:
- Use https to access balancer management page.
choices: ["true", "false"]
type: bool
default: 'no'
validate_certs:
default: true
description:
- Validate ssl/tls certificates.
choices: ["true", "false"]
type: bool
default: 'yes'
'''
EXAMPLES = '''

26
lib/ansible/modules/web_infrastructure/deploy_helper.py
View File

@@ -45,9 +45,6 @@ options:
Returned in the C(deploy_helper.project_path) fact.
state:
required: False
choices: [ present, finalize, absent, clean, query ]
default: present
description:
- the state of the project.
C(query) will only gather facts,
@@ -56,57 +53,52 @@ options:
deployed release and optionally clean old releases,
C(clean) will remove failed & old releases,
C(absent) will remove the project folder (synonymous to the M(file) module with C(state=absent))
choices: [ present, finalize, absent, clean, query ]
default: present
release:
required: False
default: None
description:
- the release version that is being deployed. Defaults to a timestamp format %Y%m%d%H%M%S (i.e. '20141119223359').
This parameter is optional during C(state=present), but needs to be set explicitly for C(state=finalize).
You can use the generated fact C(release={{ deploy_helper.new_release }}).
releases_path:
required: False
default: releases
description:
- the name of the folder that will hold the releases. This can be relative to C(path) or absolute.
Returned in the C(deploy_helper.releases_path) fact.
default: releases
shared_path:
required: False
default: shared
description:
- the name of the folder that will hold the shared resources. This can be relative to C(path) or absolute.
If this is set to an empty string, no shared folder will be created.
Returned in the C(deploy_helper.shared_path) fact.
default: shared
current_path:
required: False
default: current
description:
- the name of the symlink that is created when the deploy is finalized. Used in C(finalize) and C(clean).
Returned in the C(deploy_helper.current_path) fact.
default: current
unfinished_filename:
required: False
default: DEPLOY_UNFINISHED
description:
- the name of the file that indicates a deploy has not finished. All folders in the releases_path that
contain this file will be deleted on C(state=finalize) with clean=True, or C(state=clean). This file is
automatically deleted from the I(new_release_path) during C(state=finalize).
default: DEPLOY_UNFINISHED
clean:
required: False
default: True
description:
- Whether to run the clean procedure in case of C(state=finalize).
type: bool
default: 'yes'
keep_releases:
required: False
default: 5
description:
- the number of old releases to keep when cleaning. Used in C(finalize) and C(clean). Any unfinished builds
will be deleted first, so only correct releases will count. The current version will not count.
default: 5
notes:
- Facts are only returned for C(state=query) and C(state=present). If you use both, you should pass any overridden

36
lib/ansible/modules/web_infrastructure/jenkins_plugin.py
View File

@@ -23,45 +23,35 @@ description:
options:
group:
required: false
default: jenkins
description:
- Name of the Jenkins group on the OS.
default: jenkins
jenkins_home:
required: false
default: /var/lib/jenkins
description:
- Home directory of the Jenkins user.
default: /var/lib/jenkins
mode:
required: false
default: '0664'
description:
- File mode applied on versioned plugins.
name:
required: true
description:
- Plugin name.
owner:
required: false
default: jenkins
description:
- Name of the Jenkins user on the OS.
default: jenkins
state:
required: false
choices: [absent, present, pinned, unpinned, enabled, disabled, latest]
default: present
description:
- Desired plugin state.
- If the C(latest) is set, the check for new version will be performed
every time. This is suitable to keep the plugin up-to-date.
choices: [absent, present, pinned, unpinned, enabled, disabled, latest]
default: present
timeout:
required: false
default: 30
description:
- Server connection timeout in secs.
default: 30
updates_expiration:
required: false
default: 86400
description:
- Number of seconds after which a new copy of the I(update-center.json)
file is downloaded. This is used to avoid the need to download the
@@ -69,21 +59,18 @@ options:
- Set it to C(0) if no cache file should be used. In that case, the
plugin file will always be downloaded to calculate its checksum when
C(latest) is specified.
default: 86400
updates_url:
required: false
default: https://updates.jenkins-ci.org
description:
- URL of the Update Centre.
- Used as the base URL to download the plugins and the
I(update-center.json) JSON file.
default: https://updates.jenkins-ci.org
url:
required: false
default: http://localhost:8080
description:
- URL of the Jenkins server.
default: http://localhost:8080
version:
required: false
default: null
description:
- Plugin version number.
- If this option is specified, all plugin dependencies must be installed
@@ -93,12 +80,11 @@ options:
- Quote the version to prevent the value to be interpreted as float. For
example if C(1.20) would be unquoted, it would become C(1.2).
with_dependencies:
required: false
choices: ['yes', 'no']
default: 'yes'
description:
- Defines whether to install plugin dependencies.
- This option takes effect only if the I(version) is not defined.
type: bool
default: 'yes'
notes:
- Plugin installation should be run under root or the same user which owns

13
lib/ansible/modules/web_infrastructure/jenkins_script.py
View File

@@ -30,41 +30,32 @@ options:
- The groovy script to be executed.
This gets passed as a string Template if args is defined.
required: true
default: null
url:
description:
- The jenkins server to execute the script against. The default is a local
jenkins instance that is not being proxied through a webserver.
required: false
default: http://localhost:8080
validate_certs:
description:
- If set to C(no), the SSL certificates will not be validated.
This should only set to C(no) used on personally controlled sites
using self-signed certificates as it avoids verifying the source site.
required: false
default: True
type: bool
default: 'yes'
user:
description:
- The username to connect to the jenkins server with.
required: false
default: null
password:
description:
- The password to connect to the jenkins server with.
required: false
default: null
timeout:
description:
- The request timeout in seconds
required: false
default: 10
version_added: "2.4"
args:
description:
- A dict of key-value pairs used in formatting the script using string.Template (see https://docs.python.org/2/library/string.html#template-strings).
required: false
default: null
notes:
- Since the script can do anything this does not report on changes.

8
lib/ansible/modules/web_infrastructure/letsencrypt.py
View File

@@ -104,8 +104,8 @@ options:
- "Boolean indicating whether you agree to the terms of service document."
- "ACME servers can require this to be true."
- This option will only be used when C(acme_version) is not 1.
default: no
type: bool
default: 'no'
version_added: "2.5"
challenge:
description: The challenge to be performed.
@@ -157,8 +157,8 @@ options:
- Whether calls to the ACME directory will validate TLS certificates.
- I(Warning:) Should I(only ever) be set to C(false) for testing purposes,
for example when testing against a local Pebble server.
default: yes
type: bool
default: 'yes'
version_added: 2.5
deactivate_authzs:
description:
@@ -168,8 +168,8 @@ options:
for a certain amount of time, and can be used to issue certificates
without having to re-authenticate the domain. This can be a security
concern. "
default: no
type: bool
default: 'no'
version_added: 2.6
force:
description:
@@ -177,8 +177,8 @@ options:
existing certificate is still valid.
- This is especially helpful when having an updated CSR e.g. with
additional domains for which a new certificate is desired.
default: no
type: bool
default: 'no'
version_added: 2.6
'''

12
lib/ansible/modules/web_infrastructure/supervisorctl.py
View File

@@ -27,42 +27,30 @@ options:
- The name will be taken as group name when it ends with a colon I(:)
- Group support is only available in Ansible version 1.6 or later.
required: true
default: null
config:
description:
- The supervisor configuration file path
required: false
default: null
version_added: "1.3"
server_url:
description:
- URL on which supervisord server is listening
required: false
default: null
version_added: "1.3"
username:
description:
- username to use for authentication
required: false
default: null
version_added: "1.3"
password:
description:
- password to use for authentication
required: false
default: null
version_added: "1.3"
state:
description:
- The desired state of program/group.
required: true
default: null
choices: [ "present", "started", "stopped", "restarted", "absent" ]
supervisorctl_path:
description:
- path to supervisorctl executable
required: false
default: null
version_added: "1.4"
notes:
- When C(state) = I(present), the module will call C(supervisorctl reread) then C(supervisorctl add) if the program/group does not exist.

10
lib/ansible/modules/web_infrastructure/taiga_issue.py
View File

@@ -26,7 +26,6 @@ options:
taiga_host:
description:
- The hostname of the Taiga instance.
required: False
default: https://api.taiga.io
project:
description:
@@ -43,42 +42,33 @@ options:
priority:
description:
- The issue priority. Must exist previously.
required: False
default: Normal
status:
description:
- The issue status. Must exist previously.
required: False
default: New
severity:
description:
- The issue severity. Must exist previously.
required: False
default: Normal
description:
description:
- The issue description.
required: False
default: ""
attachment:
description:
- Path to a file to be attached to the issue.
required: False
default: None
attachment_description:
description:
- A string describing the file to be attached to the issue.
required: False
default: ""
tags:
description:
- A lists of tags to be assigned to the issue.
required: False
default: []
state:
description:
- Whether the issue should be present or not.
required: False
choices: ["present", "absent"]
default: present
author: Alejandro Guirao (@lekum)