Refine template, add special example generation code

Author: Simran-B

3.11/release-notes-new-features311.md

@@ -296,7 +296,7 @@ which means you cannot use `RETURN NEW` or similar to access the new documents
 including their document keys. Additionally, all preceding calculations must be
 constant, which excludes any subqueries that read documents.
 
-See the [List of optimizer rules](aql/execution-and-performance-optimizer.html#list-of-optimizer-rules)
+See the list of [optimizer rules](aql/execution-and-performance-optimizer.html#optimizer-rules)
 for details.
 
 ### Index cache refilling

3.12/aql/examples-upsert-repsert.md

@@ -318,8 +318,8 @@ the same way as the `INSERT` AQL operation can do.
 
 AQL `INSERT` queries with the `optimize-cluster-multiple-document-operations`
 optimization applied perform similarly well in cluster deployments, but it
-cannot be applied in all cases (see the
-[List of optimizer rules](execution-and-performance-optimizer.html#list-of-optimizer-rules)
+cannot be applied in all cases (see the list of
+[optimizer rules](execution-and-performance-optimizer.html#optimizer-rules)
 for details).
 
 ## Summary

3.12/aql/execution-and-performance-explaining-queries.md

@@ -82,13 +82,13 @@ The result object also contains a `warnings` attribute, which is an array of
 warnings that occurred during optimization or execution plan creation.
 
 Each plan in the result is an object with the following attributes:
-- `nodes`: the array of execution nodes of the plan. See the
-  [list of execution nodes](execution-and-performance-optimizer.html#list-of-execution-nodes)
+- `nodes`: the array of execution nodes of the plan. See the list of
+  [execution nodes](execution-and-performance-optimizer.html#execution-nodes)
 - `estimatedCost`: the total estimated cost for the plan. If there are multiple
   plans, the optimizer chooses the plan with the lowest total cost.
 - `collections`: an array of collections used in the query
-- `rules`: an array of rules the optimizer applied. See the
-  [list of optimizer rules](execution-and-performance-optimizer.html#list-of-optimizer-rules)
+- `rules`: an array of rules the optimizer applied. See the list of
+  [optimizer rules](execution-and-performance-optimizer.html#optimizer-rules)
 - `variables`: array of variables used in the query (note: this may contain
   internal variables created by the optimizer)
 

3.12/aql/execution-and-performance-optimizer.md

@@ -68,7 +68,7 @@ As you can see, the result details are very verbose. They are not covered in
 detail for brevity in the next sections. Instead, let's take a closer look at
 the results step by step.
 
-#### Execution nodes
+#### Execution nodes of a query
 
 In general, an execution plan can be considered to be a pipeline of processing steps.
 Each processing step is carried out by a so-called *execution node*
@@ -116,7 +116,7 @@ Here is a summary:
 - CalculationNode: calculates return value `i.value`
 - ReturnNode: returns data to the caller
 
-#### Optimizer rules
+#### Optimizer rules used for a query
 
 Note that in the example, the optimizer has optimized the `SORT` statement away.
 It can do it safely because there is a sorted persistent index on `i.value`, which it has
@@ -162,7 +162,7 @@ Note that some rules may appear multiple times in the list, with number suffixes
 This is due to the same rule being applied multiple times, at different positions
 in the optimizer pipeline.
 
-Also see the full [List of optimizer rules](#list-of-optimizer-rules) below.
+Also see the full list of [optimizer rules](#optimizer-rules) below.
 
 #### Collections used in a query
 
@@ -490,12 +490,29 @@ Optimizer rules
 
 ### List of optimizer rules
 
-The following optimizer rules may appear in the `rules` attribute of a plan.
-
-Some rules may appear multiple times in the list of applied optimizations, with
-number suffixes like `-2`, (e.g. `remove-unnecessary-calculations-2`). This is
-due to the same rule being applied multiple times at different optimization stages.
-
+The following user-facing optimizer rules exist and are enabled by default
+unless noted otherwise. You can
+[enable and disable optimizer rules](#turning-specific-optimizer-rules-off)
+except for a few required rules.
+
+Some rules exist multiple times with number suffixes like `-2`,
+(e.g. `remove-unnecessary-calculations-2`). This is due to the same rule being
+applied multiple times at different optimization stages.
+
+{% comment %} Execute code but exclude its output from rendering
+
+    @startDocuBlockInline 00_dumpOptimizerRules_cluster
+    @EXAMPLE_ARANGOSH_RUN{00_dumpOptimizerRules_cluster}
+      var url = "/_api/query/rules";
+      var rules = internal.arango.GET(url);
+      assert(Array.isArray(rules));
+      assert(rules.some(e => e.clusterOnly));
+      var outfile = "Documentation/optimizer-rules.json"
+      assert(fs.write(outfile, JSON.stringify(rules, undefined, 2)));
+    @END_EXAMPLE_ARANGOSH_RUN
+    @endDocuBlock 00_dumpOptimizerRules_cluster
+
+{% endcomment %}
 {% assign rulesFile = page.version.version | remove: "." | append: "-optimizer-rules" -%}
 {% assign options = site.data[rulesFile] -%}
 {% include aql-optimizer-rules.md options=options %}

3.12/release-notes-new-features35.md

@@ -171,7 +171,7 @@ If the optimization is applied, it will show as "sort-limit" rule in the query e
 plan.
 
 Also see:
-- [AQL Optimizer Rules](aql/execution-and-performance-optimizer.html#list-of-optimizer-rules)
+- [AQL Optimizer Rules](aql/execution-and-performance-optimizer.html#optimizer-rules)
   (`sort-limit` rule)
 - [Sort-Limit Optimization in AQL](https://www.arangodb.com/2019/03/sort-limit-optimization-aql/){:target="_blank"}
   (blog post)

3.12/release-notes-new-features36.md

@@ -269,7 +269,7 @@ FOR d IN myView
 The respective optimizer rules are called `late-document-materialization`
 (collection source) and `late-document-materialization-arangosearch`
 (ArangoSearch View source). If applied, you will find `MaterializeNode`s
-in [execution plans](aql/execution-and-performance-optimizer.html#list-of-execution-nodes).
+in [execution plans](aql/execution-and-performance-optimizer.html#execution-nodes).
 
 ### Parallelization of cluster AQL queries
 

_includes/aql-optimizer-rules.md

@@ -1,19 +1,23 @@
 {% assign rules=include.options -%}
 {% for rule in rules -%}
-{% if rule.hidden == false -%}
+{% if rule.flags.hidden == false -%}
 #### `{{ rule.name }}`
 
-{% if rule.enterpriseOnly %}
+{% if rule.flags.enterpriseOnly %}
 _Enterprise Edition only_
 {% endif %}
 
 {{ rule.description }}
 
-{% if rule.disabledByDefault == false %}
-Default: enabled
+{% if rule.flags.disabledByDefault -%}
+This rule is disabled by default.
 {% endif %}
 
-{% if rule.clusterOnly %}
+{% if rule.flags.canBeDisabled == false -%}
+This is not an optimization and cannot be turned off.
+{% endif %}
+
+{% if rule.flags.clusterOnly -%}
 Only available in cluster deployments.
 {% endif %}