Docs: Add deprecation check for dashboard loading.

libbeat/docs/command-reference.asciidoc

@@ -20,12 +20,22 @@
 :modules-command-short-desc: Manages configured modules
 :run-command-short-desc: Runs {beatname_uc}. This command is used by default if you start {beatname_uc} without specifying a command
 
+ifndef::deprecate_dashboard_loading[]
+
 ifdef::has_ml_jobs[]
 :setup-command-short-desc: Sets up the initial environment, including the index template, Kibana dashboards (when available), and machine learning jobs (when available)
 endif::[]
 
 ifndef::has_ml_jobs[]
-:setup-command-short-desc: Sets up the initial environment, including the index template, Kibana dashboards (when available)
+:setup-command-short-desc: Sets up the initial environment, including the index template and Kibana dashboards (when available)
+endif::[]
+
+endif::[]
+
+ifdef::deprecate_dashboard_loading[]
+
+:setup-command-short-desc: Sets up the initial environment, including the ES index template and Kibana dashboards (deprecated).
+
 endif::[]
 
 :test-command-short-desc: Tests the configuration
@@ -39,9 +49,17 @@ endif::[]
 <titleabbrev>Command reference</titleabbrev>
 ++++
 
+ifndef::deprecate_dashboard_loading[]
 {beatname_uc} provides a command-line interface for starting {beatname_uc} and
-performing common tasks, like testing configuration files and loading
-dashboards. The command-line also supports <<global-flags,global flags>>
+performing common tasks, like testing configuration files and loading dashboards.
+endif::[]
+
+ifdef::deprecate_dashboard_loading[]
+{beatname_uc} provides a command-line interface for starting {beatname_uc} and
+performing common tasks, like testing configuration files and loading dashboards (deprecated).
+endif::[]
+
+The command-line also supports <<global-flags,global flags>>
 for controlling global behaviors.
 
 ifeval::["{beatname_lc}"!="winlogbeat"]
@@ -391,8 +409,19 @@ the end of the file is reached. By default harvesters are closed after
 endif::[]
 
 *`--setup`*::
-Loads the sample Kibana dashboards. If you want to load the dashboards without
-running {beatname_uc}, use the <<setup-command,`setup`>> command instead.
+ifdef::deprecate_dashboard_loading[]
+deprecated[{deprecate_dashboard_loading}]
+endif::[]
++
+ifdef::has_ml_jobs[]
+Loads the initial setup, including Elasticsearch template, Kibana index pattern,
+Kibana dashboards and Machine learning jobs.
+endif::[]
+ifndef::has_ml_jobs[]
+Loads the initial setup, including Elasticsearch template, Kibana index pattern and Kibana dashboards.
+endif::[]
+If you want to use the command without running {beatname_uc}, use the <<setup-command,`setup`>> command instead.
+
 
 ifeval::["{beatname_lc}"=="metricbeat"]
 
@@ -431,13 +460,17 @@ Or:
 [[setup-command]]
 ==== `setup` command
 
-{setup-command-short-desc}.
+{setup-command-short-desc}
 
 * The index template ensures that fields are mapped correctly in Elasticsearch.
+
 * The Kibana dashboards make it easier for you to visualize {beatname_uc} data
 in Kibana.
+
+ifdef::has_ml_jobs[]
 * The machine learning jobs contain the configuration information and metadata
 necessary to analyze data for anomalies.
+endif::[]
 
 Use this command instead of `run --setup` when you want to set up the
 environment without actually running {beatname_uc} and ingesting data.
@@ -452,18 +485,32 @@ environment without actually running {beatname_uc} and ingesting data.
 
 *FLAGS*
 
+ifndef::deprecate_dashboard_loading[]
 *`--dashboards`*::
 Sets up the Kibana dashboards only. This option loads the dashboards from the
 {beatname_uc} package. For more options, such as loading customized dashboards,
 see {beatsdevguide}/import-dashboards.html[Importing Existing Beat Dashboards]
 in the _Beats Developer Guide_.
+endif::[]
+
+ifdef::deprecate_dashboard_loading[]
+*`--dashboards`*::
+
+deprecated[{deprecate_dashboard_loading}]
++
+Sets up the Kibana dashboards only.
+endif::[]
 
 *`-h, --help`*::
 Shows help for the `setup` command.
 
+ifdef::has_ml_jobs[]
+
 *`--machine-learning`*::
 Sets up machine learning job configurations only.
 
+endif::[]
+
 ifeval::["{beatname_lc}"=="filebeat"]
 
 *`--modules MODULE_LIST`*::

libbeat/docs/dashboardsconfig.asciidoc

@@ -11,6 +11,11 @@
 
 [[configuration-dashboards]]
 == Load the Kibana dashboards
+ifdef::deprecate_dashboard_loading[]
+
+deprecated[{deprecate_dashboard_loading}]
+
+endif::[]
 
 {beatname_uc} comes packaged with example Kibana dashboards, visualizations,
 and searches for visualizing {beatname_uc} data in Kibana.

libbeat/docs/outputconfig.asciidoc

@@ -216,10 +216,16 @@ The index name to write events to. The default is
 +"{beatname_lc}-%\{[beat.version]\}-%\{+yyyy.MM.dd\}"+ (for example,
 +"{beatname_lc}-{version}-2017.04.26"+). If you change this setting, you also
 need to configure the `setup.template.name` and `setup.template.pattern` options
-(see <<configuration-template>>). If you are using the pre-built Kibana
-dashboards, you also need to set the `setup.dashboards.index` option (see
-<<configuration-dashboards>>).
+(see <<configuration-template>>).
 
+If you are using the pre-built Kibana dashboards,
+you also need to set the `setup.dashboards.index` option (see <<configuration-dashboards>>).
+
+ifdef::deprecate_dashboard_loading[]
+
+deprecated[{deprecate_dashboard_loading}]
+
+endif::[]
 
 ===== `indices`
 
@@ -378,7 +384,7 @@ The Logstash output sends events directly to Logstash by using the lumberjack
 protocol, which runs over TCP. Logstash allows for additional processing and routing of
 generated events.
 
-include::../../libbeat/docs/shared-logstash-config.asciidoc[]
+include::./shared-logstash-config.asciidoc[]
 
 ==== Accessing metadata fields
 

libbeat/docs/shared-kibana-config.asciidoc

@@ -11,6 +11,11 @@
 
 [[setup-kibana-endpoint]]
 == Set up the Kibana endpoint
+ifdef::deprecate_dashboard_loading[]
+
+deprecated[{deprecate_dashboard_loading}]
+
+endif::[]
 
 ifeval::["{beatname_lc}" == "apm-server"]
 The Kibana dashboards are loaded into Kibana via the Kibana API.

libbeat/docs/shared-template-load.asciidoc

@@ -94,18 +94,37 @@ that you specify should include the root name of the index plus version and
 date information. You also need to configure the `setup.template.name` and
 `setup.template.pattern` options to match the new name. For example:
 +
+ifndef::deprecate_dashboard_loading[]
+
 ["source","sh",subs="attributes,callouts"]
 -----
 output.elasticsearch.index: "customname-%{[beat.version]}-%{+yyyy.MM.dd}"
 setup.template.name: "customname"
 setup.template.pattern: "customname-*"
 setup.dashboards.index: "customname-*" <1>
 -----
+
 <1> If you plan to
 <<load-kibana-dashboards, set up the Kibana dashboards>>, also set
 this option to overwrite the index name defined in the dashboards and index
 pattern.
 
+endif::[]
+
+ifdef::deprecate_dashboard_loading[]
+
+["source","sh",subs="attributes,callouts"]
+-----
+output.elasticsearch.index: "customname-%{[beat.version]}-%{+yyyy.MM.dd}"
+setup.template.name: "customname"
+setup.template.pattern: "customname-*"
+-----
++
+Also ensure to change the index name accordingly in the Kibana dashboards,
+when loading via the Kibana UI.
+
+endif::[]
+
 See <<configuration-template>> for the full list of configuration options.