Merge pull request #854 from untergeek/doc/842

Improve documentation for filter chaining [skip ci]

docs/Changelog.rst

@@ -21,7 +21,11 @@ Changelog
 
 **Documentation**
 
+  * Add docs regarding how filters are ANDed together, and how to do an OR with
+    the regex pattern filter type. Requested in #842 (untergeek)
   * Fix typo in Click version in docs. #850 (breml)
+  * Where applicable, replace `[source,text]` with `[source,yaml]` for better
+    formatting in the resulting docs.
 
 4.2.4 (7 December 2016)
 -----------------------

docs/asciidoc/actions.asciidoc

@@ -24,7 +24,7 @@ once created, can only be deleted.
 [[alias]]
 == Alias
 
-[source,text]
+[source,yaml]
 -------------
 action: alias
 description: "Add/Remove selected indices to or from the specified alias"
@@ -57,7 +57,7 @@ The <<option_extra_settings,extra_settings>> option allows the addition of extra
 settings with the `add` directive.  These settings are ignored for `remove`.  An
 example of how these settings can be used to create a filtered alias might be:
 
-[source,text]
+[source,yaml]
 -------------
 extra_settings:
   filter:
@@ -95,7 +95,7 @@ TIP: See an example of this action in an <<actionfile,actionfile>>
 [[allocation]]
 == Allocation
 
-[source,text]
+[source,yaml]
 -------------
 action: allocation
 description: "Apply shard allocation filtering rules to the specified indices"
@@ -154,7 +154,7 @@ TIP: See an example of this action in an <<actionfile,actionfile>>
 [[close]]
 == Close
 
-[source,text]
+[source,yaml]
 -------------
 action: close
 description: "Close selected indices"
@@ -193,7 +193,7 @@ TIP: See an example of this action in an <<actionfile,actionfile>>
 [[cluster_routing]]
 == Cluster Routing
 
-[source,text]
+[source,yaml]
 -------------
 action: cluster_routing
 description: "Apply routing rules to the entire cluster"
@@ -250,7 +250,7 @@ TIP: See an example of this action in an <<actionfile,actionfile>>
 [[create_index]]
 == Create Index
 
-[source,text]
+[source,yaml]
 -------------
 action: create_index
 description: "Create index as named"
@@ -272,7 +272,7 @@ The <<option_extra_settings,extra_settings>> option allows the addition of extra
 settings, such as index settings and mappings.  An example of how these settings
 can be used to create an index might be:
 
-[source,text]
+[source,yaml]
 -------------
 extra_settings:
   settings:
@@ -311,7 +311,7 @@ TIP: See an example of this action in an <<actionfile,actionfile>>
 [[delete_indices]]
 == Delete Indices
 
-[source,text]
+[source,yaml]
 -------------
 action: delete_indices
 description: "Delete selected indices"
@@ -347,7 +347,7 @@ TIP: See an example of this action in an <<actionfile,actionfile>>
 [[delete_snapshots]]
 == Delete Snapshots
 
-[source,text]
+[source,yaml]
 -------------
 action: delete_snapshots
 description: "Delete selected snapshots from 'repository'"
@@ -399,7 +399,7 @@ TIP: See an example of this action in an <<actionfile,actionfile>>
 [[open]]
 == Open
 
-[source,text]
+[source,yaml]
 -------------
 action: open
 description: "open selected indices"
@@ -435,7 +435,7 @@ TIP: See an example of this action in an <<actionfile,actionfile>>
 [[forcemerge]]
 == Forcemerge
 
-[source,text]
+[source,yaml]
 -------------
 action: forcemerge
 description: "Perform a forceMerge on selected indices to 'max_num_segments' per shard"
@@ -483,7 +483,7 @@ TIP: See an example of this action in an <<actionfile,actionfile>>
 [[replicas]]
 == Replicas
 
-[source,text]
+[source,yaml]
 -------------
 action: replicas
 description: >- Set the number of replicas per shard for selected
@@ -534,7 +534,7 @@ TIP: See an example of this action in an <<actionfile,actionfile>>
 [[restore]]
 == Restore
 
-[source,text]
+[source,yaml]
 -------------
 actions:
   1:
@@ -584,7 +584,7 @@ The <<option_extra_settings,extra_settings>> option allows the addition of extra
 settings, such as index settings and mappings.  An example of how these settings
 can be used to change settings for an index being restored might be:
 
-[source,text]
+[source,yaml]
 -------------
 extra_settings:
   settings:
@@ -639,7 +639,7 @@ TIP: See an example of this action in an <<actionfile,actionfile>>
 [[snapshot]]
 == Snapshot
 
-[source,text]
+[source,yaml]
 -------------
 action: snapshot
 description: >-

docs/asciidoc/configuration.asciidoc

@@ -157,7 +157,7 @@ documentation.
 This is an optional description which can help describe what the action and its
 filters are supposed to do.
 
-[source,text]
+[source,yaml]
 -------------
 description: >- I can make the description span multiple
     lines by putting ">-" at the beginning of the line,

docs/asciidoc/examples.asciidoc

@@ -26,7 +26,7 @@ configuration files.
 [[ex_alias]]
 == alias
 
-[source,text]
+[source,yaml]
 -------------
 ---
 # Remember, leave a key empty if there is no value.  None will be a string,
@@ -84,7 +84,7 @@ actions:
 [[ex_allocation]]
 == allocation
 
-[source,text]
+[source,yaml]
 -------------
 ---
 # Remember, leave a key empty if there is no value.  None will be a string,
@@ -124,7 +124,7 @@ actions:
 [[ex_close]]
 == close
 
-[source,text]
+[source,yaml]
 -------------
 ---
 # Remember, leave a key empty if there is no value.  None will be a string,
@@ -162,7 +162,7 @@ actions:
 [[ex_cluster_routing]]
 == cluster_routing
 
-[source,text]
+[source,yaml]
 -------------
 ---
 # Remember, leave a key empty if there is no value.  None will be a string,
@@ -209,7 +209,7 @@ actions:
 [[ex_create_index]]
 == create_index
 
-[source,text]
+[source,yaml]
 -------------
 ---
 # Remember, leave a key empty if there is no value.  None will be a string,
@@ -237,7 +237,7 @@ actions:
 [[ex_delete_indices]]
 == delete_indices
 
-[source,text]
+[source,yaml]
 -------------
 ---
 # Remember, leave a key empty if there is no value.  None will be a string,
@@ -275,7 +275,7 @@ actions:
 [[ex_delete_snapshots]]
 == delete_snapshots
 
-[source,text]
+[source,yaml]
 -------------
 ---
 # Remember, leave a key empty if there is no value.  None will be a string,
@@ -312,7 +312,7 @@ actions:
 [[ex_forcemerge]]
 == forcemerge
 
-[source,text]
+[source,yaml]
 -------------
 ---
 # Remember, leave a key empty if there is no value.  None will be a string,
@@ -352,7 +352,7 @@ actions:
 [[ex_open]]
 == open
 
-[source,text]
+[source,yaml]
 -------------
 ---
 # Remember, leave a key empty if there is no value.  None will be a string,
@@ -395,7 +395,7 @@ actions:
 [[ex_replicas]]
 == replicas
 
-[source,text]
+[source,yaml]
 -------------
 ---
 # Remember, leave a key empty if there is no value.  None will be a string,
@@ -432,7 +432,7 @@ actions:
 [[ex_restore]]
 == restore
 
-[source,text]
+[source,yaml]
 -------------
 ---
 # Remember, leave a key empty if there is no value.  None will be a string,
@@ -480,7 +480,7 @@ actions:
 [[ex_snapshot]]
 == snapshot
 
-[source,text]
+[source,yaml]
 -------------
 ---
 # Remember, leave a key empty if there is no value.  None will be a string,

docs/asciidoc/faq.asciidoc

@@ -162,7 +162,7 @@ The last index can be deleted with a regular expression of `'.*e$'`.
 
 The resulting <<actionfile,actionfile>> might look like this:
 
-[source,text]
+[source,yaml]
 --------
 actions:
   1:

docs/asciidoc/filter_elements.asciidoc

@@ -234,6 +234,8 @@ This setting tells the <<filtertype_pattern,pattern>> what pattern type to
 match. Acceptable values for this setting are `prefix`, `suffix`, `timestring`,
 and `regex`.
 
+include::inc_filter_chaining.asciidoc[]
+
 There is no default value. This setting must be set by the user or an exception
 will be raised, and execution will halt.