From 9e3a729da9599aa2751a7ed0afb4bf68401ab400 Mon Sep 17 00:00:00 2001 From: Felix Fontein Date: Sat, 7 Jan 2023 11:03:58 +0100 Subject: [PATCH] Improve callback docs (#5760) * Improve callback docs. * Apply suggestions from code review Co-authored-by: Alexei Znamensky <103110+russoz@users.noreply.github.com> * Update plugins/callback/logentries.py Co-authored-by: Alexei Znamensky <103110+russoz@users.noreply.github.com> * More improvements. Co-authored-by: Alexei Znamensky <103110+russoz@users.noreply.github.com> Co-authored-by: Alexei Znamensky <103110+russoz@users.noreply.github.com> --- plugins/callback/cgroup_memory_recap.py | 12 ++++++------ plugins/callback/context_demo.py | 4 ++-- plugins/callback/counter_enabled.py | 2 +- plugins/callback/dense.py | 2 +- plugins/callback/jabber.py | 4 ++-- plugins/callback/log_plays.py | 4 ++-- plugins/callback/logdna.py | 12 ++++++------ plugins/callback/logentries.py | 18 +++++++++--------- plugins/callback/logstash.py | 12 ++++++------ plugins/callback/null.py | 2 +- plugins/callback/say.py | 6 +++--- plugins/callback/selective.py | 2 +- plugins/callback/slack.py | 6 +++--- plugins/callback/splunk.py | 10 +++++----- plugins/callback/sumologic.py | 6 +++--- plugins/callback/syslog_json.py | 10 +++++----- plugins/callback/yaml.py | 2 +- 17 files changed, 57 insertions(+), 57 deletions(-) diff --git a/plugins/callback/cgroup_memory_recap.py b/plugins/callback/cgroup_memory_recap.py index eedacfeecb..ccdbcc9cf0 100644 --- a/plugins/callback/cgroup_memory_recap.py +++ b/plugins/callback/cgroup_memory_recap.py @@ -16,15 +16,15 @@ DOCUMENTATION = ''' - cgroups short_description: Profiles maximum memory usage of tasks and full execution using cgroups description: - - This is an ansible callback plugin that profiles maximum memory usage of ansible and individual tasks, and displays a recap at the end using cgroups + - This is an ansible callback plugin that profiles maximum memory usage of ansible and individual tasks, and displays a recap at the end using cgroups. notes: - - Requires ansible to be run from within a cgroup, such as with C(cgexec -g memory:ansible_profile ansible-playbook ...) - - This cgroup should only be used by ansible to get accurate results - - To create the cgroup, first use a command such as C(sudo cgcreate -a ec2-user:ec2-user -t ec2-user:ec2-user -g memory:ansible_profile) + - Requires ansible to be run from within a cgroup, such as with C(cgexec -g memory:ansible_profile ansible-playbook ...). + - This cgroup should only be used by ansible to get accurate results. + - To create the cgroup, first use a command such as C(sudo cgcreate -a ec2-user:ec2-user -t ec2-user:ec2-user -g memory:ansible_profile). options: max_mem_file: required: true - description: Path to cgroups C(memory.max_usage_in_bytes) file. Example C(/sys/fs/cgroup/memory/ansible_profile/memory.max_usage_in_bytes) + description: Path to cgroups C(memory.max_usage_in_bytes) file. Example C(/sys/fs/cgroup/memory/ansible_profile/memory.max_usage_in_bytes). env: - name: CGROUP_MAX_MEM_FILE ini: @@ -32,7 +32,7 @@ DOCUMENTATION = ''' key: max_mem_file cur_mem_file: required: true - description: Path to C(memory.usage_in_bytes) file. Example C(/sys/fs/cgroup/memory/ansible_profile/memory.usage_in_bytes) + description: Path to C(memory.usage_in_bytes) file. Example C(/sys/fs/cgroup/memory/ansible_profile/memory.usage_in_bytes). env: - name: CGROUP_CUR_MEM_FILE ini: diff --git a/plugins/callback/context_demo.py b/plugins/callback/context_demo.py index 9c3c9c5afc..b9558fc064 100644 --- a/plugins/callback/context_demo.py +++ b/plugins/callback/context_demo.py @@ -13,8 +13,8 @@ DOCUMENTATION = ''' type: aggregate short_description: demo callback that adds play/task context description: - - Displays some play and task context along with normal output - - This is mostly for demo purposes + - Displays some play and task context along with normal output. + - This is mostly for demo purposes. requirements: - whitelist in configuration ''' diff --git a/plugins/callback/counter_enabled.py b/plugins/callback/counter_enabled.py index e0e040c9d4..555ebd29a6 100644 --- a/plugins/callback/counter_enabled.py +++ b/plugins/callback/counter_enabled.py @@ -21,7 +21,7 @@ DOCUMENTATION = ''' extends_documentation_fragment: - default_callback requirements: - - set as stdout callback in ansible.cfg (stdout_callback = counter_enabled) + - set as stdout callback in C(ansible.cfg) (C(stdout_callback = counter_enabled)) ''' from ansible import constants as C diff --git a/plugins/callback/dense.py b/plugins/callback/dense.py index 18e4f162ff..490705fd27 100644 --- a/plugins/callback/dense.py +++ b/plugins/callback/dense.py @@ -14,7 +14,7 @@ short_description: minimal stdout output extends_documentation_fragment: - default_callback description: -- When in verbose mode it will act the same as the default callback +- When in verbose mode it will act the same as the default callback. author: - Dag Wieers (@dagwieers) requirements: diff --git a/plugins/callback/jabber.py b/plugins/callback/jabber.py index 823ae20144..d2d00496d8 100644 --- a/plugins/callback/jabber.py +++ b/plugins/callback/jabber.py @@ -13,10 +13,10 @@ DOCUMENTATION = ''' type: notification short_description: post task events to a jabber server description: - - The chatty part of ChatOps with a Hipchat server as a target + - The chatty part of ChatOps with a Hipchat server as a target. - This callback plugin sends status updates to a HipChat channel during playbook execution. requirements: - - xmpp (python lib https://github.com/ArchipelProject/xmpppy) + - xmpp (Python library U(https://github.com/ArchipelProject/xmpppy)) options: server: description: connection info to jabber server diff --git a/plugins/callback/log_plays.py b/plugins/callback/log_plays.py index b1dc69364c..e99054e176 100644 --- a/plugins/callback/log_plays.py +++ b/plugins/callback/log_plays.py @@ -13,10 +13,10 @@ DOCUMENTATION = ''' type: notification short_description: write playbook output to log file description: - - This callback writes playbook output to a file per host in the C(/var/log/ansible/hosts) directory + - This callback writes playbook output to a file per host in the C(/var/log/ansible/hosts) directory. requirements: - Whitelist in configuration - - A writeable /var/log/ansible/hosts directory by the user executing Ansible on the controller + - A writeable C(/var/log/ansible/hosts) directory by the user executing Ansible on the controller options: log_folder: default: /var/log/ansible/hosts diff --git a/plugins/callback/logdna.py b/plugins/callback/logdna.py index 2d0880ce19..fc9a81ac8a 100644 --- a/plugins/callback/logdna.py +++ b/plugins/callback/logdna.py @@ -12,14 +12,14 @@ DOCUMENTATION = ''' type: notification short_description: Sends playbook logs to LogDNA description: - - This callback will report logs from playbook actions, tasks, and events to LogDNA (https://app.logdna.com) + - This callback will report logs from playbook actions, tasks, and events to LogDNA (U(https://app.logdna.com)). requirements: - - LogDNA Python Library (https://github.com/logdna/python) + - LogDNA Python Library (U(https://github.com/logdna/python)) - whitelisting in configuration options: conf_key: required: true - description: LogDNA Ingestion Key + description: LogDNA Ingestion Key. type: string env: - name: LOGDNA_INGESTION_KEY @@ -28,7 +28,7 @@ DOCUMENTATION = ''' key: conf_key plugin_ignore_errors: required: false - description: Whether to ignore errors on failing or not + description: Whether to ignore errors on failing or not. type: boolean env: - name: ANSIBLE_IGNORE_ERRORS @@ -38,7 +38,7 @@ DOCUMENTATION = ''' default: false conf_hostname: required: false - description: Alternative Host Name; the current host name by default + description: Alternative Host Name; the current host name by default. type: string env: - name: LOGDNA_HOSTNAME @@ -47,7 +47,7 @@ DOCUMENTATION = ''' key: conf_hostname conf_tags: required: false - description: Tags + description: Tags. type: string env: - name: LOGDNA_TAGS diff --git a/plugins/callback/logentries.py b/plugins/callback/logentries.py index d40939b0ab..22322a4df2 100644 --- a/plugins/callback/logentries.py +++ b/plugins/callback/logentries.py @@ -13,15 +13,15 @@ DOCUMENTATION = ''' short_description: Sends events to Logentries description: - This callback plugin will generate JSON objects and send them to Logentries via TCP for auditing/debugging purposes. - - Before 2.4, if you wanted to use an ini configuration, the file must be placed in the same directory as this plugin and named logentries.ini + - Before 2.4, if you wanted to use an ini configuration, the file must be placed in the same directory as this plugin and named C(logentries.ini). - In 2.4 and above you can just put it in the main Ansible configuration file. requirements: - whitelisting in configuration - - certifi (python library) - - flatdict (python library), if you want to use the 'flatten' option + - certifi (Python library) + - flatdict (Python library), if you want to use the 'flatten' option options: api: - description: URI to the Logentries API + description: URI to the Logentries API. env: - name: LOGENTRIES_API default: data.logentries.com @@ -29,7 +29,7 @@ DOCUMENTATION = ''' - section: callback_logentries key: api port: - description: HTTP port to use when connecting to the API + description: HTTP port to use when connecting to the API. env: - name: LOGENTRIES_PORT default: 80 @@ -37,7 +37,7 @@ DOCUMENTATION = ''' - section: callback_logentries key: port tls_port: - description: Port to use when connecting to the API when TLS is enabled + description: Port to use when connecting to the API when TLS is enabled. env: - name: LOGENTRIES_TLS_PORT default: 443 @@ -45,7 +45,7 @@ DOCUMENTATION = ''' - section: callback_logentries key: tls_port token: - description: The logentries "TCP token" + description: The logentries C(TCP token). env: - name: LOGENTRIES_ANSIBLE_TOKEN required: true @@ -54,7 +54,7 @@ DOCUMENTATION = ''' key: token use_tls: description: - - Toggle to decide whether to use TLS to encrypt the communications with the API server + - Toggle to decide whether to use TLS to encrypt the communications with the API server. env: - name: LOGENTRIES_USE_TLS default: false @@ -63,7 +63,7 @@ DOCUMENTATION = ''' - section: callback_logentries key: use_tls flatten: - description: flatten complex data structures into a single dictionary with complex keys + description: Flatten complex data structures into a single dictionary with complex keys. type: boolean default: false env: diff --git a/plugins/callback/logstash.py b/plugins/callback/logstash.py index 7666b47876..144e1f9915 100644 --- a/plugins/callback/logstash.py +++ b/plugins/callback/logstash.py @@ -13,13 +13,13 @@ DOCUMENTATION = r''' type: notification short_description: Sends events to Logstash description: - - This callback will report facts and task events to Logstash https://www.elastic.co/products/logstash + - This callback will report facts and task events to Logstash U(https://www.elastic.co/products/logstash). requirements: - whitelisting in configuration - - logstash (python library) + - logstash (Python library) options: server: - description: Address of the Logstash server + description: Address of the Logstash server. env: - name: LOGSTASH_SERVER ini: @@ -28,7 +28,7 @@ DOCUMENTATION = r''' version_added: 1.0.0 default: localhost port: - description: Port on which logstash is listening + description: Port on which logstash is listening. env: - name: LOGSTASH_PORT ini: @@ -37,7 +37,7 @@ DOCUMENTATION = r''' version_added: 1.0.0 default: 5000 type: - description: Message type + description: Message type. env: - name: LOGSTASH_TYPE ini: @@ -54,7 +54,7 @@ DOCUMENTATION = r''' env: - name: LOGSTASH_PRE_COMMAND format_version: - description: Logging format + description: Logging format. type: str version_added: 2.0.0 ini: diff --git a/plugins/callback/null.py b/plugins/callback/null.py index 01f5f6ca06..f53a242945 100644 --- a/plugins/callback/null.py +++ b/plugins/callback/null.py @@ -15,7 +15,7 @@ DOCUMENTATION = ''' - set as main display callback short_description: Don't display stuff to screen description: - - This callback prevents outputing events to screen + - This callback prevents outputing events to screen. ''' from ansible.plugins.callback import CallbackBase diff --git a/plugins/callback/say.py b/plugins/callback/say.py index 03d7060352..005725a22b 100644 --- a/plugins/callback/say.py +++ b/plugins/callback/say.py @@ -14,12 +14,12 @@ DOCUMENTATION = ''' type: notification requirements: - whitelisting in configuration - - the '/usr/bin/say' command line program (standard on macOS) or 'espeak' command line program + - the C(/usr/bin/say) command line program (standard on macOS) or C(espeak) command line program short_description: notify using software speech synthesizer description: - - This plugin will use the 'say' or 'espeak' program to "speak" about play events. + - This plugin will use the C(say) or C(espeak) program to "speak" about play events. notes: - - In 2.8, this callback has been renamed from C(osx_say) into M(community.general.say). + - In Ansible 2.8, this callback has been renamed from C(osx_say) into M(community.general.say). ''' import platform diff --git a/plugins/callback/selective.py b/plugins/callback/selective.py index 6476f5ba53..526975bd2c 100644 --- a/plugins/callback/selective.py +++ b/plugins/callback/selective.py @@ -22,7 +22,7 @@ DOCUMENTATION = ''' options: nocolor: default: false - description: This setting allows suppressing colorizing output + description: This setting allows suppressing colorizing output. env: - name: ANSIBLE_NOCOLOR - name: ANSIBLE_SELECTIVE_DONT_COLORIZE diff --git a/plugins/callback/slack.py b/plugins/callback/slack.py index 6ca15b43f5..e9b84bbb38 100644 --- a/plugins/callback/slack.py +++ b/plugins/callback/slack.py @@ -18,11 +18,11 @@ DOCUMENTATION = ''' short_description: Sends play events to a Slack channel description: - This is an ansible callback plugin that sends status updates to a Slack channel during playbook execution. - - Before 2.4 only environment variables were available for configuring this plugin + - Before Ansible 2.4 only environment variables were available for configuring this plugin. options: webhook_url: required: true - description: Slack Webhook URL + description: Slack Webhook URL. env: - name: SLACK_WEBHOOK_URL ini: @@ -45,7 +45,7 @@ DOCUMENTATION = ''' - section: callback_slack key: username validate_certs: - description: validate the SSL certificate of the Slack server. (For HTTPS URLs) + description: Validate the SSL certificate of the Slack server for HTTPS URLs. env: - name: SLACK_VALIDATE_CERTS ini: diff --git a/plugins/callback/splunk.py b/plugins/callback/splunk.py index 32e77f4eb4..67ad944d2e 100644 --- a/plugins/callback/splunk.py +++ b/plugins/callback/splunk.py @@ -13,22 +13,22 @@ DOCUMENTATION = ''' author: "Stuart Hirst (!UNKNOWN) " description: - This callback plugin will send task results as JSON formatted events to a Splunk HTTP collector. - - The companion Splunk Monitoring & Diagnostics App is available here "https://splunkbase.splunk.com/app/4023/" + - The companion Splunk Monitoring & Diagnostics App is available here U(https://splunkbase.splunk.com/app/4023/). - Credit to "Ryan Currah (@ryancurrah)" for original source upon which this is based. requirements: - Whitelisting this callback plugin - 'Create a HTTP Event Collector in Splunk' - - 'Define the url and token in ansible.cfg' + - 'Define the URL and token in C(ansible.cfg)' options: url: - description: URL to the Splunk HTTP collector source + description: URL to the Splunk HTTP collector source. env: - name: SPLUNK_URL ini: - section: callback_splunk key: url authtoken: - description: Token to authenticate the connection to the Splunk HTTP collector + description: Token to authenticate the connection to the Splunk HTTP collector. env: - name: SPLUNK_AUTHTOKEN ini: @@ -48,7 +48,7 @@ DOCUMENTATION = ''' version_added: '1.0.0' include_milliseconds: description: Whether to include milliseconds as part of the generated timestamp field in the event - sent to the Splunk HTTP collector + sent to the Splunk HTTP collector. env: - name: SPLUNK_INCLUDE_MILLISECONDS ini: diff --git a/plugins/callback/sumologic.py b/plugins/callback/sumologic.py index 6fd950d991..998081c35b 100644 --- a/plugins/callback/sumologic.py +++ b/plugins/callback/sumologic.py @@ -12,14 +12,14 @@ type: notification short_description: Sends task result events to Sumologic author: "Ryan Currah (@ryancurrah)" description: - - This callback plugin will send task results as JSON formatted events to a Sumologic HTTP collector source + - This callback plugin will send task results as JSON formatted events to a Sumologic HTTP collector source. requirements: - Whitelisting this callback plugin - 'Create a HTTP collector source in Sumologic and specify a custom timestamp format of C(yyyy-MM-dd HH:mm:ss ZZZZ) and a custom timestamp locator of C("timestamp": "(.*)")' options: url: - description: URL to the Sumologic HTTP collector source + description: URL to the Sumologic HTTP collector source. env: - name: SUMOLOGIC_URL ini: @@ -28,7 +28,7 @@ options: ''' EXAMPLES = ''' -examples: > +examples: | To enable, add this to your ansible.cfg file in the defaults block [defaults] callback_whitelist = community.general.sumologic diff --git a/plugins/callback/syslog_json.py b/plugins/callback/syslog_json.py index 4b2c7e79b8..2bd8f6e604 100644 --- a/plugins/callback/syslog_json.py +++ b/plugins/callback/syslog_json.py @@ -15,11 +15,11 @@ DOCUMENTATION = ''' - whitelist in configuration short_description: sends JSON events to syslog description: - - This plugin logs ansible-playbook and ansible runs to a syslog server in JSON format - - Before Ansible 2.9 only environment variables were available for configuration + - This plugin logs ansible-playbook and ansible runs to a syslog server in JSON format. + - Before Ansible 2.9 only environment variables were available for configuration. options: server: - description: syslog server that will receive the event + description: Syslog server that will receive the event. env: - name: SYSLOG_SERVER default: localhost @@ -27,7 +27,7 @@ DOCUMENTATION = ''' - section: callback_syslog_json key: syslog_server port: - description: port on which the syslog server is listening + description: Port on which the syslog server is listening. env: - name: SYSLOG_PORT default: 514 @@ -35,7 +35,7 @@ DOCUMENTATION = ''' - section: callback_syslog_json key: syslog_port facility: - description: syslog facility to log as + description: Syslog facility to log as. env: - name: SYSLOG_FACILITY default: user diff --git a/plugins/callback/yaml.py b/plugins/callback/yaml.py index 81d59e2e70..73782de151 100644 --- a/plugins/callback/yaml.py +++ b/plugins/callback/yaml.py @@ -11,7 +11,7 @@ DOCUMENTATION = ''' author: Unknown (!UNKNOWN) name: yaml type: stdout - short_description: yaml-ized Ansible screen output + short_description: YAML-ized Ansible screen output description: - Ansible output that can be quite a bit easier to read than the default JSON formatting.