Additional X-Ray Documentation (#39466)

This just expands the documentation in the primary x-ray namespace (`metabase.automagic-dashboards.core`). At this point, someone new to the namespace should be able to get into the x-ray code without difficulty.

src/metabase/automagic_dashboards/core.clj

 (ns metabase.automagic-dashboards.core
-  "Automatically generate questions and dashboards based on predefined heuristics.
+  "# Automagic Dashboards #
+
+  Automatically generate questions and dashboards based on predefined heuristics.
+
+  Note that the primary entry point into this namespace is `automagic-analysis`. This function primarily gathers
+  needed data about the input value and any special options then calls into `automagic-dashboard`, where most of
+  the work occurs.
 
   There are two key inputs to this algorithm:
   - An entity to generate the dashboard for. The primary data needed from this entity is:
     - The entity type itself
     - The field information, especially the metadata about these fields
-  - A set of potential dashboard templates from which a dashboard can be realized based on the entity and field data
+    - This data gathering happens in the `->root` function
+  - A dashboard template from which a dashboard can be realized based on the entity and field data
+
+  ## Template Selection ##
+
+  Within the `automagic-dashboard` function, a template is selected based on the entity type being analyzed unless a
+  dashboard template is specified in the argument. This is a critically important fact:
+
+  ** The template selection is based on the entity type of the item being x-rayed.  **
+
+  Example: X-raying the \"ORDERS\" table will result in matching the template
+  `resources/automagic_dashboards/table/TransactionTable.yaml`.
+
+  This is because the `:entity_type` of the table is `:entity/TransactionTable` as can be seen here:
+
+  ```clojure
+  (t2/select-one-fn :entity_type :model/Table :name \"ORDERS\")
+  ;=> :entity/TransactionTable
+  ```
+
+  _Most_ tables and _all_ models (as of this writing) will bottom out at `:entity/GenericTable` and thus, use the
+  `resources/automagic_dashboards/table/GenericTable.yaml` template. `:entity_type` for a given table type is made in
+  the `metabase.sync.analyze.classifiers.name/infer-entity-type` function, where the primary logic is table naming
+  based on the `prefix-or-postfix` var in that ns.
 
-  The first step in the base `automagic-dashboard` is to select dashboard templates that match the entity type of
-  the entity to be x-rayed. A simple entity might match only to a GenericTable template while a more complicated
-  entity might match to a TransactionTable or EventTable template.
+  ProTip: If you want to introduce a new template type, do the following:
 
-  Once potential templates are selected, the following process is attempted for each template in order of most
-  specialized template to least:
-  - Determine which entity fields map to dimensions and metrics described in the template.
-  - Match these selected dimensions and metrics to required dimensions and metrics for cards specified in the template.
-  - If any cards match, we successfully return a dashboard generated with the created cards.
+  1. Update `prefix-or-postfix` to include the match logic and new entity type
+  2. Add a template file, `resources/automagic_dashboards/table/NewEntityType.yaml`, where NewEntityType is the new
+     entity type (e.g. `:entity/NewEntityType`).
+
+  ## Template Files ##
+
+  Template files define a potential dashboard, potentially including titles, seconds, cards, filters, and more.
+  They are found in `resources/automagic_dashboards`. Once you've read through several, the format should be fairly
+  self-explanatory, but here are a few critical details:
+
+  - Templated strings are matched with `[[double square brackets]]`
+  - `title`, `transient_title`, and `description` should be self-explanatory
+  - The fundamental \"dynamic\" building blocks are:
+    - dimensions - The base building block in the process. Dimensions map to the columns of the entity being x-rayed
+      and are matched by dimension field_type to entity type (semantic, effective, etc.). These form the x-axis in a
+      card and the breakout column of a query.
+    - metrics - Metrics form the y-axis in a card and are the aggregates in a query. They are always defined in terms
+      of 0 or more dimensions. Metrics can be dimensionless quantities (e.g. count), based on a single value (e.g.
+      average of a column), or a more complicated expression (e.g. ratio of average of column 1 and average of column 2).
+    - filters - Filters add a filter clause to a query and are also defined in terms of dimensions.
+    - cards - The final product of the dynamic process. Cards are built from predefined metrics, dimensions, and
+      filters as discussed above along with preferences such as display type and title.
+    - groups - Dashboard sections in which matching cards are added.
+
+  ## The Dynamic Binding and Dashboard Generation Process ##
+
+  Once data has been accreted in `automagic-analysis`, `automagic-dashboard` will first select a template as described
+  above. It then calls `metabase.automagic-dashboards.interesting/identify` which takes the actual column data and
+  dimension, metric, and filter definitions from the template and matches all potential columns to potential dimensions,
+  metrics, and filters. The resulting \"grounded-values\" are now passed into `generate-dashboard`, which matches all
+  of these values to card templates to produce a dashboard. The majority of the card generation work is done in
+  `metabase.automagic-dashboards.combination/grounded-metrics->dashcards`.
+
+  Note that if a card template's dimensions, metrics, and filters are not matched to grounded values the card will not
+  be generated. Conversely, if a card template can be matched by multiple combinations of dimensions, multiple cards
+  may be generated.
+
+  Once a selection of cards have been generated, the top N are selected (default 15), added to the dashboard, and grouped.
+
+  ## Example ##
 
   The following example is provided to better illustrate the template process and how dimensions and metrics work.
 
@@ -61,10 +123,10 @@
    - A field from an unspecified table with semantic type `:type/Income` and score of 90
    - A field from a Sales table with semantic type `:type/Number` and score of 50
 
-   When matched with actual fields from an x-rayed entity, the highest matching field is selected to be \"bound\" to
-   the Income dimensions. Suppose you have an entity of type SalesTable and fields of INCOME (semantic type Income),
-   TAX (type Float), and TOTAL (Float). In this case, the INCOME field would match best (score 100) and be bound to the
-   Income dimension.
+   When matched with actual fields from an x-rayed entity, the highest matching field, by score, is selected to be
+   \"bound\" to the Income dimensions. Suppose you have an entity of type SalesTable and fields of INCOME (semantic
+   type Income), TAX (type Float), and TOTAL (Float). In this case, the INCOME field would match best (score 100)
+   and be bound to the Income dimension.
 
    The other specified dimensions will have similar matching rules. Note that X & Y are, like all other dimensions,
    *named* dimensions. In our above example the Income dimension matched to the INCOME field of type `:type/Income`.
@@ -725,7 +787,13 @@
     (generate-dashboard base-context template grounded-values)))
 
 (defmulti automagic-analysis
-  "Create a transient dashboard analyzing given entity."
+  "Create a transient dashboard analyzing given entity.
+
+  This function eventually calls out to `automagic-dashboard` with two primary arguments:
+  - The item to be analyzed. This entity is a 'decorated' version of the raw input that has been
+    passed through the `->root` function, which is an aggregate including the original entity, its
+    source, what dashboard template categories to apply, etc.
+  - Additional options such as how many cards to show, a cell query (a drill through), etc."
   {:arglists '([entity opts])}
   (fn [entity _]
     (mi/model entity)))