Clean up Grafana docs a bit (#37516)

* Clean up Grafana docs a bit But more is needed, default values, missing choices, proper descriptions, actual sentences :-) * Remove validate-modules entries
2018-03-17 02:53:26 +01:00 · 2018-03-17 02:53:26 +01:00 · 51662acc6c
commit 51662acc6c
parent 775e8ed806
4 changed files with 112 additions and 137 deletions
--- a/lib/ansible/modules/monitoring/grafana_dashboard.py
+++ b/lib/ansible/modules/monitoring/grafana_dashboard.py
@ -1,7 +1,7 @@
 #!/usr/bin/python
 # -*- coding: utf-8 -*-
-#
-# Copyright 2017, Thierry Sallé (@tsalle)
+
+# Copyright: (c) 2017, Thierry Sallé (@tsalle)
 # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)

 from __future__ import absolute_import, division, print_function
@ -16,80 +16,76 @@ DOCUMENTATION = '''
 ---
 module: grafana_dashboard
 author:
-  - "Thierry Sallé (@tsalle)"
+  - Thierry Sallé (@tsalle)
 version_added: "2.5"
-short_description: Manage grafana dashboards
+short_description: Manage Grafana dashboards
 description:
-  - Create, update, delete, export grafana dashboards via API
+  - Create, update, delete, export Grafana dashboards via API.
 options:
  grafana_url:
+    description:
+      - The Grafana URL.
    required: true
-    description:
-      - Grafana url
  grafana_user:
-    required: false
-    default: admin
    description:
-      - Grafana API user
+      - The Grafana API user.
+    default: admin
  grafana_password:
-    required: false
+    description:
+      - The Grafana API password.
    default: admin
-    description:
-      - Grafana API password
  grafana_api_key:
-    required: false
    description:
-      - Grafana API key
-      - If set, I(grafana_user) and I(grafana_password) will be ignored
+      - The Grafana API key.
+      - If set, I(grafana_user) and I(grafana_password) will be ignored.
  org_id:
-    required: false
    description:
-      - Grafana Organisation ID where the dashboard will be imported / exported
-      - Not used when I(grafana_api_key) is set, because the grafana_api_key only belong to one organisation.
+      - The Grafana Organisation ID where the dashboard will be imported / exported.
+      - Not used when I(grafana_api_key) is set, because the grafana_api_key only belong to one organisation..
    default: 1
  state:
-    required: true
-    default: present
    description:
      - State of the dashboard.
-    choices: ['present', 'absent', 'export']
+    required: true
+    choices: [ absent, export, present ]
+    default: present
  slug:
    description:
      - slug of the dashboard. It's the friendly url name of the dashboard.
-      - When state is present, this parameter can override the slug in the meta section of the json file.
+      - When C(state) is C(present), this parameter can override the slug in the meta section of the json file.
      - If you want to import a json dashboard exported directly from the interface (not from the api),
-      - you have to specify the slug parameter because there is no meta section in the exported json.
+        you have to specify the slug parameter because there is no meta section in the exported json.
  path:
    description:
-      - path to the json file containing the grafana dashboard to import or export.
+      - The path to the json file containing the Grafana dashboard to import or export.
  overwrite:
-    default: false
    description:
-      - override existing dashboard when state is present.
+      - Override existing dashboard when state is present.
+    type: bool
+    default: 'no'
  message:
    description:
      - Set a commit message for the version history.
-      - Only used when state is present
+      - Only used when C(state) is C(present).
  validate_certs:
-    default: true
-    type: bool
    description:
-      - If C(no), SSL certificates will not be validated. This should only be used
-      - on personally controlled sites using self-signed certificates.
+      - If C(no), SSL certificates will not be validated.
+      - This should only be used on personally controlled sites using self-signed certificates.
+    type: bool
+    default: 'yes'
 '''

 EXAMPLES = '''
---
- name: import grafana dashboard foo
+- name: Import Grafana dashboard foo
  grafana_dashboard:
    grafana_url: http://grafana.company.com
    grafana_api_key: XXXXXXXXXXXX
    state: present
-    message: "updated by ansible"
-    overwrite: true
+    message: Updated by ansible
+    overwrite: yes
    path: /path/to/dashboards/foo.json

- name: export dashboard
+- name: Export dashboard
  grafana_dashboard:
    grafana_url: http://grafana.company.com
    grafana_api_key: XXXXXXXXXXXX
--- a/lib/ansible/modules/monitoring/grafana_datasource.py
+++ b/lib/ansible/modules/monitoring/grafana_datasource.py
@ -1,7 +1,7 @@
 #!/usr/bin/python
 # -*- coding: utf-8 -*-
-#
-# Copyright 2017, Thierry Sallé (@tsalle)
+
+# Copyright: (c) 2017, Thierry Sallé (@tsalle)
 # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)

 from __future__ import absolute_import, division, print_function
@ -16,171 +16,152 @@ DOCUMENTATION = '''
 ---
 module: grafana_datasource
 author:
-  - "Thierry Sallé (@tsalle)"
+  - Thierry Sallé (@tsalle)
 version_added: "2.5"
-short_description: Manage grafana datasources
+short_description: Manage Grafana datasources
 description:
-  - Create/update/delete grafana datasources via API
+  - Create/update/delete Grafana datasources via API.
 options:
  grafana_url:
-    required: true
    description:
-      - Grafana url
+      - The Grafana URL.
+    required: true
  name:
-    required: true
    description:
-      - Name of the datasource
+      - The name of the datasource.
+    required: true
  ds_type:
-    required: true
-    choices: [graphite,prometheus,elasticsearch,influxdb,opentsdb,mysql,postgres]
    description:
-     - Type of the datasource
+     - The type of the datasource.
+    required: true
+    choices: [ elasticsearch, graphite, influxdb, mysql, opentsdb, postgres, prometheus ]
  url:
+    description:
+      - The URL of the datasource.
    required: true
-    description:
-      - Url of the datasource
  access:
-    required: false
+    description:
+      - The access mode for this datasource.
+    choices: [ direct, proxy ]
    default: proxy
-    choices: [proxy,direct]
-    description:
-      - Access mode for this datasource
  grafana_user:
-    required: false
-    default: admin
    description:
-      - Grafana API user
+      - The Grafana API user.
+    default: admin
  grafana_password:
-    required: false
+    description:
+      - The Grafana API password.
    default: admin
-    description:
-      - Grafana API password
  grafana_api_key:
-    required: false
    description:
-      - Grafana API key
-      - If set, grafana_user and grafana_password will be ignored
+      - The Grafana API key.
+      - If set, C(grafana_user) and C(grafana_password) will be ignored.
  database:
-    required: false
    description:
      - Name of the database for the datasource.
-      - This options is required when the ds_type is influxdb, elasticsearch (index name), mysql or postgres
+      - This options is required when the C(ds_type) is C(influxdb), C(elasticsearch) (index name), C(mysql) or C(postgres).
+    required: false
  user:
-    required: false
    description:
-      - Datasource login user for influxdb datasources
+      - The datasource login user for influxdb datasources.
  password:
-    required: false
    description:
-      - Datasource password
+      - The datasource password
  basic_auth_user:
-    required: false
    description:
-      - Datasource basic auth user.
+      - The datasource basic auth user.
      - Setting this option with basic_auth_password will enable basic auth.
  basic_auth_password:
-    required: false
    description:
-      - Datasource basic auth password, when basic auth is true
+      - The datasource basic auth password, when C(basic auth) is C(yes).
  with_credentials:
-    required: false
-    default: false
    description:
      - Whether credentials such as cookies or auth headers should be sent with cross-site requests.
+    type: bool
+    default: 'no'
  tls_client_cert:
-    required: false
    description:
-      - client tls certificate.
-      - If tls_client_cert and tls_client_key are set, this will enable tls auth.
-      - begins with ----- BEGIN CERTIFICATE -----
+      - The client TLS certificate.
+      - If C(tls_client_cert) and C(tls_client_key) are set, this will enable TLS authentication.
+      - Starts with ----- BEGIN CERTIFICATE -----
  tls_client_key:
-    required: false
    description:
-      - client tls private key
-      - befins with ----- BEGIN RSA PRIVATE KEY -----
+      - The client TLS private key
+      - Starts with ----- BEGIN RSA PRIVATE KEY -----
  tls_ca_cert:
-    required: false
    description:
-      - tls ca certificate for self signed certificates.
-      - only used when tls_client_cert and tls_client_key are set
+      - The TLS CA certificate for self signed certificates.
+      - Only used when C(tls_client_cert) and C(tls_client_key) are set.
  is_default:
-    required: false
-    default: false
    description:
-      - Make this datasource the default one
+      - Make this datasource the default one.
+    type: bool
+    default: 'no'
  org_id:
-    required: false
    description:
-      - Grafana Organisation ID in which the datasource should be created
-      - Not used when grafana_api_key is set, because the grafana_api_key only belong to one organisation.
+      - Grafana Organisation ID in which the datasource should be created.
+      - Not used when C(grafana_api_key) is set, because the C(grafana_api_key) only belong to one organisation.
    default: 1
  state:
-    required: false
-    default: present
-    choices: [present, absent]
    description:
      - Status of the datasource
+    choices: [ absent, present ]
+    default: present
  es_version:
-    required: false
-    default: 5
-    choices: [2, 5, 56]
    description:
-      - Elasticsearch version (for ds_type = elasticsearch only)
-      - Version 56 is for elasticsearch 5.6+ where tou can specify the max_concurrent_shard_requests option.
+      - Elasticsearch version (for C(ds_type = elasticsearch) only)
+      - Version 56 is for elasticsearch 5.6+ where tou can specify the C(max_concurrent_shard_requests) option.
+    choices: [ 2, 5, 56 ]
+    default: 5
  max_concurrent_shard_requests:
-    required: false
-    default: 256
    description:
      - Starting with elasticsearch 5.6, you can specify the max concurrent shard per requests.
+    default: 256
  time_field:
-    required: false
-    default: timestamp
    description:
-      - Name of the time field in elasticsearch ds
+      - Name of the time field in elasticsearch ds.
      - For example C(@timestamp)
+    default: timestamp
  time_interval:
-    required: false
    description:
-      - Minimum group by interval for influxdb or elasticsearch datasources
-      - for example '>10s'
+      - Minimum group by interval for C(influxdb) or C(elasticsearch) datasources.
+      - for example C(>10s)
  interval:
-    required: false
+    description:
+      - For elasticsearch C(ds_type), this is the index pattern used.
    choices: ['', 'Hourly', 'Daily', 'Weekly', 'Monthly', 'Yearly']
-    description:
-      - for elasticsearch ds_type, this is the index pattern used.
  tsdb_version:
-    required: false
-    choices: [1, 2, 3]
    description:
-      - opentsdb version (1 for <= 2.1, 2 for ==2.2, 3 for ==2.3)
+      - The opentsdb version.
+      - Use C(1) for <=2.1, C(2) for ==2.2, C(3) for ==2.3.
+    choices: [ 1, 2, 3 ]
    default: 1
  tsdb_resolution:
-    required: false
-    choices: [second, millisecond]
    description:
-      - opentsdb time resolution
-    default: 1
+      - The opentsdb time resolution.
+    choices: [ millisecond, second ]
+    default: second
  sslmode:
-    choices: ['disable','require','verify-ca','verify-full']
    description:
-      - SSL mode for postgres datasoure type.
+      - SSL mode for C(postgres) datasoure type.
+    choices: [ disable, require, verify-ca, verify-full ]
  validate_certs:
-    required: false
-    default: True
    description:
-      - Validate or not grafana certificate
+      - Whether to validate the Grafana certificate.
+    type: bool
+    default: 'yes'
 '''

 EXAMPLES = '''
 ---
- name: create elasticsearch datasource
+- name: Create elasticsearch datasource
  grafana_datasource:
    name: my_elastic
    grafana_url: http://grafana.company.com
    type: elasticsearch
    url: https://elasticsearch.company.com:9200
    database: my-index_*
-    basic_auth: true
+    basic_auth: yes
    basic_auth_user: grafana
    basic_auth_password: xxxxxxxx
    json_data: '{"esVersion":5, "timeField": "@timestamp"}'
--- a/lib/ansible/modules/monitoring/grafana_plugin.py
+++ b/lib/ansible/modules/monitoring/grafana_plugin.py
@ -1,7 +1,7 @@
 #!/usr/bin/python
 # -*- coding: utf-8 -*-
-#
-# Copyright 2017, Thierry Sallé (@tsalle)
+
+# Copyright: (c) 2017, Thierry Sallé (@tsalle)
 # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)

 from __future__ import absolute_import, division, print_function
@ -16,20 +16,20 @@ DOCUMENTATION = '''
 ---
 module: grafana_plugin
 author:
-  - "Thierry Sallé (@tsalle)"
+  - Thierry Sallé (@tsalle)
 version_added: "2.5"
 short_description: Manage Grafana plugins via grafana-cli
 description:
  - Install and remove Grafana plugins.
 options:
  name:
-    required: true
    description:
      - Name of the plugin.
+    required: true
  version:
    description:
      - Version of the plugin to install.
-      - Default to latest
+      - Default to latest.
  grafana_plugins_dir:
    description:
      - Directory where Grafana plugin will be installed.
@ -38,19 +38,19 @@ options:
      - Grafana repository. If not set, gafana-cli will use the default value C(https://grafana.net/api/plugins).
  grafana_plugin_url:
    description:
-      - Custom Grafana plugin URL
-      - Require grafana 4.6.x or later
+      - Custom Grafana plugin URL.
+      - Requires grafana 4.6.x or later.
  state:
-    default: present
-    choices: [present, absent]
    description:
      - Status of the Grafana plugin.
      - If latest is set, the version parameter will be ignored.
+    choices: [ absent, present ]
+    default: present
 '''

 EXAMPLES = '''
 ---
- name: install - update Grafana piechart panel plugin
+- name: Install - update Grafana piechart panel plugin
  grafana_plugin:
    name: grafana-piechart-panel
    version: latest
--- a/test/sanity/validate-modules/ignore.txt
+++ b/test/sanity/validate-modules/ignore.txt
@ -911,9 +911,7 @@ lib/ansible/modules/monitoring/datadog_event.py E324
 lib/ansible/modules/monitoring/datadog_monitor.py E324
 lib/ansible/modules/monitoring/datadog_monitor.py E325
 lib/ansible/modules/monitoring/datadog_monitor.py E326
-lib/ansible/modules/monitoring/grafana_dashboard.py E325
 lib/ansible/modules/monitoring/grafana_datasource.py E324
-lib/ansible/modules/monitoring/grafana_datasource.py E325
 lib/ansible/modules/monitoring/icinga2_host.py E322
 lib/ansible/modules/monitoring/icinga2_host.py E324
 lib/ansible/modules/monitoring/logentries.py E322