[docs] Restructure and refactor beats documentation (#16825) (#16965)

elastic · Mar 11, 2020 · c9efdf3 · c9efdf3
1 parent 00116d8
commit c9efdf3
Show file tree

Hide file tree

Showing 114 changed files with 768 additions and 388 deletions.
diff --git a/auditbeat/docs/auditbeat-filtering.asciidoc b/auditbeat/docs/auditbeat-filtering.asciidoc
@@ -1,5 +1,9 @@
 [[filtering-and-enhancing-data]]
-== Filter and enhance the exported data
+== Filter and enhance data with processors
+
+++++
+<titleabbrev>Processors</titleabbrev>
+++++
 
 include::{libbeat-dir}/processors.asciidoc[]
 

diff --git a/auditbeat/docs/auditbeat-general-options.asciidoc b/auditbeat/docs/auditbeat-general-options.asciidoc
@@ -1,5 +1,9 @@
 [[configuration-general-options]]
-== Specify general settings
+== Configure general settings
+
+++++
+<titleabbrev>General settings</titleabbrev>
+++++
 
 You can specify settings in the +{beatname_lc}.yml+ config file to control the
 general behavior of {beatname_uc}.

diff --git a/auditbeat/docs/auditbeat-modules-config.asciidoc b/auditbeat/docs/auditbeat-modules-config.asciidoc
@@ -1,5 +1,9 @@
 [id="configuration-{beatname_lc}"]
-== Specify which modules to run
+== Configure modules
+
+++++
+<titleabbrev>Modules</titleabbrev>
+++++
 
 To enable specific modules you add entries to the `auditbeat.modules` list in
 the +{beatname_lc}.yml+ config file. Each entry in the list begins with a dash

diff --git a/auditbeat/docs/configuring-howto.asciidoc b/auditbeat/docs/configuring-howto.asciidoc
@@ -1,8 +1,12 @@
 [id="configuring-howto-{beatname_lc}"]
-= Configuring {beatname_uc}
+= Configure {beatname_uc}
 
 [partintro]
 --
+++++
+<titleabbrev>Configure</titleabbrev>
+++++
+
 Before modifying configuration settings, make sure you've completed the
 <<{beatname_lc}-configuration,configuration steps>> in the Getting Started.
 This section describes some common use cases for changing configuration options.
@@ -21,23 +25,19 @@ The following topics describe how to configure {beatname_uc}:
 
 * <<configuration-{beatname_lc}>>
 * <<configuration-general-options>>
-* <<{beatname_lc}-configuration-reloading>>
-* <<configuring-internal-queue>>
+* <<configuration-path>>
+* <<auditbeat-configuration-reloading>>
 * <<configuring-output>>
-* <<ilm>>
 * <<configuration-ssl>>
-* <<filtering-and-enhancing-data>>
-* <<configuring-ingest-node>>
-* <<{beatname_lc}-geoip>>
-* <<configuration-path>>
+* <<ilm>>
+* <<configuration-template>>
 * <<setup-kibana-endpoint>>
 * <<configuration-dashboards>>
-* <<configuration-template>>
+* <<filtering-and-enhancing-data>>
+* <<configuring-internal-queue>>
 * <<configuration-logging>>
-* <<using-environ-vars>>
-* <<yaml-tips>>
-* <<regexp-support>>
 * <<http-endpoint>>
+* <<regexp-support>>
 * <<{beatname_lc}-reference-yml>>
 
 After changing configuration settings, you need to restart {beatname_uc} to
@@ -49,40 +49,26 @@ include::./auditbeat-modules-config.asciidoc[]
 
 include::./auditbeat-general-options.asciidoc[]
 
-include::./reload-configuration.asciidoc[]
+include::{libbeat-dir}/shared-path-config.asciidoc[]
 
-include::{libbeat-dir}/queueconfig.asciidoc[]
+include::./reload-configuration.asciidoc[]
 
 include::{libbeat-dir}/outputconfig.asciidoc[]
 
-include::{libbeat-dir}/shared-ilm.asciidoc[]
-
 include::{libbeat-dir}/shared-ssl-config.asciidoc[]
 
-include::./auditbeat-filtering.asciidoc[]
-
-include::{libbeat-dir}/shared-config-ingest.asciidoc[]
-
-include::{libbeat-dir}/shared-geoip.asciidoc[]
+include::{libbeat-dir}/shared-ilm.asciidoc[]
 
-include::{libbeat-dir}/shared-path-config.asciidoc[]
+include::{libbeat-dir}/setup-config.asciidoc[]
 
-include::{libbeat-dir}/shared-kibana-config.asciidoc[]
+include::./auditbeat-filtering.asciidoc[]
 
-include::{libbeat-dir}/setup-config.asciidoc[]
+include::{libbeat-dir}/queueconfig.asciidoc[]
 
 include::{libbeat-dir}/loggingconfig.asciidoc[]
 
-:standalone:
-include::{libbeat-dir}/shared-env-vars.asciidoc[]
-:standalone!:
-
-:standalone:
-include::{libbeat-dir}/yaml.asciidoc[]
-:standalone!:
+include::{libbeat-dir}/http-endpoint.asciidoc[]
 
 include::{libbeat-dir}/regexp.asciidoc[]
 
-include::{libbeat-dir}/http-endpoint.asciidoc[]
-
 include::{libbeat-dir}/reference-yml.asciidoc[]
diff --git a/auditbeat/docs/getting-started.asciidoc b/auditbeat/docs/getting-started.asciidoc
@@ -1,5 +1,9 @@
 [id="{beatname_lc}-getting-started"]
-== Getting started with {beatname_uc}
+== Get started with {beatname_uc}
+
+++++
+<titleabbrev>Get started</titleabbrev>
+++++
 
 include::{libbeat-dir}/shared-getting-started-intro.asciidoc[]
 

diff --git a/auditbeat/docs/howto/howto.asciidoc b/auditbeat/docs/howto/howto.asciidoc
@@ -0,0 +1,29 @@
+[[howto-guides]]
+= How to
+
+[partintro]
+--
+Learn how to perform common {beatname_uc} configuration tasks.
+
+* <<{beatname_lc}-geoip>>
+* <<using-environ-vars>>
+* <<configuring-ingest-node>>
+* <<yaml-tips>>
+
+
+--
+
+include::{libbeat-dir}/shared-geoip.asciidoc[]
+
+:standalone:
+include::{libbeat-dir}/shared-env-vars.asciidoc[]
+:standalone!:
+
+include::{libbeat-dir}/shared-config-ingest.asciidoc[]
+
+:standalone:
+include::{libbeat-dir}/yaml.asciidoc[]
+:standalone!:
+
+
+
diff --git a/auditbeat/docs/index.asciidoc b/auditbeat/docs/index.asciidoc
@@ -39,6 +39,8 @@ include::./upgrading.asciidoc[]
 
 include::./configuring-howto.asciidoc[]
 
+include::{docdir}/howto/howto.asciidoc[]
+
 include::./modules.asciidoc[]
 
 include::./fields.asciidoc[]

diff --git a/auditbeat/docs/reload-configuration.asciidoc b/auditbeat/docs/reload-configuration.asciidoc
@@ -1,6 +1,10 @@
 [id="{beatname_lc}-configuration-reloading"]
 == Reload the configuration dynamically
 
+++++
+<titleabbrev>Config file reloading</titleabbrev>
+++++
+
 beta[]
 
 You can configure {beatname_uc} to dynamically reload configuration files when

diff --git a/auditbeat/docs/setting-up-running.asciidoc b/auditbeat/docs/setting-up-running.asciidoc
@@ -5,7 +5,11 @@
 /////
 
 [[setting-up-and-running]]
-== Setting up and running {beatname_uc}
+== Set up and run {beatname_uc}
+
+++++
+<titleabbrev>Set up and run</titleabbrev>
+++++
 
 Before reading this section, see the
 <<{beatname_lc}-getting-started,getting started documentation>> for basic

diff --git a/auditbeat/docs/troubleshooting.asciidoc b/auditbeat/docs/troubleshooting.asciidoc
@@ -1,5 +1,5 @@
 [[troubleshooting]]
-= Troubleshooting
+= Troubleshoot
 
 [partintro]
 --

diff --git a/auditbeat/docs/upgrading.asciidoc b/auditbeat/docs/upgrading.asciidoc
@@ -1,7 +1,7 @@
 [[upgrading-auditbeat]]
-== Upgrading Auditbeat
+== Upgrade Auditbeat
 
 For information about upgrading to a new version, see the following topics in the _Beats Platform Reference_:
 
 * {beats-ref}/breaking-changes.html[Breaking Changes]
-* {beats-ref}/upgrading.html[Upgrading]
+* {beats-ref}/upgrading.html[Upgrade]
diff --git a/filebeat/docs/configuring-howto.asciidoc b/filebeat/docs/configuring-howto.asciidoc
@@ -1,8 +1,12 @@
 [[configuring-howto-filebeat]]
-= Configuring Filebeat
+= Configure {beatname_uc}
 
 [partintro]
 --
+++++
+<titleabbrev>Configure</titleabbrev>
+++++
+
 Before modifying configuration settings, make sure you've completed the
 <<filebeat-configuration,configuration steps>> in the Getting Started.
 This section describes some common use cases for changing configuration options.
@@ -19,84 +23,57 @@ _Beats Platform Reference_ for more about the structure of the config file.
 
 The following topics describe how to configure Filebeat:
 
-* <<configuration-filebeat-modules>>
 * <<configuration-filebeat-options>>
-* <<multiline-examples>>
 * <<configuration-general-options>>
+* <<configuration-path>>
 * <<filebeat-configuration-reloading>>
-* <<configuring-internal-queue>>
 * <<configuring-output>>
-* <<ilm>>
-* <<load-balancing>>
 * <<configuration-ssl>>
-* <<filtering-and-enhancing-data>>
-* <<{beatname_lc}-deduplication>>
-* <<configuring-ingest-node>>
-* <<{beatname_lc}-geoip>>
-* <<configuration-path>>
+* <<ilm>>
+* <<configuration-template>>
 * <<setup-kibana-endpoint>>
 * <<configuration-dashboards>>
-* <<configuration-template>>
-* <<configuration-logging>>
-* <<using-environ-vars>>
+* <<filtering-and-enhancing-data>>
 * <<configuration-autodiscover>>
-* <<yaml-tips>>
-* <<regexp-support>>
+* <<configuring-internal-queue>>
+* <<load-balancing>>
+* <<configuration-logging>>
 * <<http-endpoint>>
+* <<regexp-support>>
 * <<{beatname_lc}-reference-yml>>
 
 --
 
-include::./filebeat-modules-options.asciidoc[]
-
 include::./filebeat-options.asciidoc[]
 
-include::./multiline.asciidoc[]
-
 include::./filebeat-general-options.asciidoc[]
 
-include::./reload-configuration.asciidoc[]
+include::{libbeat-dir}/shared-path-config.asciidoc[]
 
-include::{libbeat-dir}/queueconfig.asciidoc[]
+include::./reload-configuration.asciidoc[]
 
 include::{libbeat-dir}/outputconfig.asciidoc[]
 
-include::../../libbeat/docs/shared-ilm.asciidoc[]
-
-include::./load-balancing.asciidoc[]
-
 include::{libbeat-dir}/shared-ssl-config.asciidoc[]
 
-include::./filebeat-filtering.asciidoc[]
-
-include::{libbeat-dir}/shared-deduplication.asciidoc[]
-
-include::{libbeat-dir}/shared-config-ingest.asciidoc[]
-
-include::{libbeat-dir}/shared-geoip.asciidoc[]
-
-include::{libbeat-dir}/shared-path-config.asciidoc[]
-
-include::{libbeat-dir}/shared-kibana-config.asciidoc[]
+include::../../libbeat/docs/shared-ilm.asciidoc[]
 
 include::{libbeat-dir}/setup-config.asciidoc[]
 
-include::{libbeat-dir}/loggingconfig.asciidoc[]
-
-:standalone:
-include::{libbeat-dir}/shared-env-vars.asciidoc[]
-:standalone!:
+include::./filebeat-filtering.asciidoc[]
 
 :autodiscoverJolokia:
 :autodiscoverHints:
 include::{libbeat-dir}/shared-autodiscover.asciidoc[]
 
-:standalone:
-include::{libbeat-dir}/yaml.asciidoc[]
-:standalone!:
+include::{libbeat-dir}/queueconfig.asciidoc[]
 
-include::{libbeat-dir}/regexp.asciidoc[]
+include::./load-balancing.asciidoc[]
+
+include::{libbeat-dir}/loggingconfig.asciidoc[]
 
 include::{libbeat-dir}/http-endpoint.asciidoc[]
 
+include::{libbeat-dir}/regexp.asciidoc[]
+
 include::{libbeat-dir}/reference-yml.asciidoc[]
diff --git a/filebeat/docs/filebeat-filtering.asciidoc b/filebeat/docs/filebeat-filtering.asciidoc
@@ -1,5 +1,9 @@
 [[filtering-and-enhancing-data]]
-== Filter and enhance the exported data
+== Filter and enhance data with processors
+
+++++
+<titleabbrev>Processors</titleabbrev>
+++++
 
 Your use case might require only a subset of the data exported by {beatname_uc},
 or you might need to enhance the exported data (for example, by adding

diff --git a/filebeat/docs/filebeat-general-options.asciidoc b/filebeat/docs/filebeat-general-options.asciidoc
@@ -1,5 +1,9 @@
 [[configuration-general-options]]
-== Specify general settings
+== Configure general settings
+
+++++
+<titleabbrev>General settings</titleabbrev>
+++++
 
 You can specify settings in the +{beatname_lc}.yml+ config file to control the
 general behavior of {beatname_uc}. This includes:

diff --git a/filebeat/docs/filebeat-modules-options.asciidoc b/filebeat/docs/filebeat-modules-options.asciidoc
@@ -1,7 +1,7 @@
 :modulename: apache mysql
 
 [id="configuration-{beatname_lc}-modules"]
-== Specify which modules to run
+== Enable and run modules
 
 NOTE: Using {beatname_uc} modules is optional. You may decide to
 <<configuration-{beatname_lc}-options,configure inputs manually>> if you are using
@@ -131,7 +131,7 @@ appropriate for your environment. To change the default configurations, you need
 to <<specify-variable-settings,specify variable settings>>.
 
 [[specify-variable-settings]]
-=== Specify variable settings
+=== Configure variable settings
 
 include::./include/set-paths.asciidoc[]
 

diff --git a/filebeat/docs/filebeat-options.asciidoc b/filebeat/docs/filebeat-options.asciidoc
@@ -2,7 +2,7 @@
 == Configure inputs
 
 ++++
-<titleabbrev>Configure inputs</titleabbrev>
+<titleabbrev>Inputs</titleabbrev>
 ++++
 
 TIP: <<{beatname_lc}-modules-overview,{beatname_uc} modules>> provide the
@@ -57,6 +57,8 @@ You can configure {beatname_uc} to use the following inputs:
 * <<{beatname_lc}-input-azure-eventhub>>
 
 
+include::multiline.asciidoc[]
+
 include::inputs/input-log.asciidoc[]
 
 include::inputs/input-stdin.asciidoc[]