(DOCSP-10974): Refactor Build Charts ToC (#371)

* (DOCSP-10974): Refactor Build Charts ToC

* Updates per reviews

* title tweak

Author: jeff-allen-mongo

config/redirects

@@ -6,7 +6,7 @@ symlink: saas -> master
 symlink: current -> 19.12
 symlink: onprem -> 19.12
 raw: charts/index.html -> ${base}/saas
-raw: charts/ -> ${base}/saas
+raw: charts/master/sort-limit-data/ -> ${base}/saas/bin-data
 raw: charts/master/administration/ -> ${base}/master
 raw: charts/master/administration/backup-and-restore-keys/ -> ${base}/master
 raw: charts/master/administration/configure-https-deployment/ -> ${base}/master
@@ -15,6 +15,7 @@ raw: charts/master/administration/start-stop-charts/ -> ${base}/master
 raw: charts/master/installation/ -> ${base}/master/launch-charts
 raw: charts/master/user-management/ -> ${base}/master
 raw: charts/master/filter-documents -> ${base}/master/filter-chart-results
+raw: charts/master/
 [19.09-19.12]: charts/${version}/pricing -> ${base}/${version}
 [19.09-19.12]: charts/${version}/launch-charts -> ${base}/${version}/installation
 [19.09-19.12]: charts/${version}/chart-type-reference/circular-charts -> ${base}/${version}/chart-type-reference/donut-chart

source/aggregation-pipeline-generation.txt

@@ -1,16 +1,19 @@
 .. _aggregation-pipeline-generation:
 
-===========================
-Charts Aggregation Pipeline 
-===========================
+============================
+Backing Aggregation Pipeline
+============================
 
 .. default-domain:: mongodb
 
-In order to get the data needed to render a chart, |charts-short| creates a MongoDB Aggregation Pipeline which is executed on the 
-MongoDB database server. The pipeline consists of multiple stages, each of which is generated based on different settings specified 
-by the chart's author. This document explains how the various Chart Builder settings are used to construct the Aggregation Pipeline. 
-You can view the pipeline used to create a chart by choosing the :guilabel:`View Aggregation Pipeline` option in the Chart Builder's 
-ellipsis dropdown on the top right.
+To get the data needed to render a chart, |charts-short| creates a
+MongoDB Aggregation Pipeline which is executed on the MongoDB database
+server. The pipeline consists of multiple stages, each of which is
+generated based on different settings specified by the chart's author.
+This document explains how the various Chart Builder settings are used
+to construct the Aggregation Pipeline. You can view the pipeline used to
+create a chart by choosing the :guilabel:`View Aggregation Pipeline`
+option in the Chart Builder's ellipsis dropdown on the top right.
 
 
 The pipeline constructed by |charts| consists of the following segments in the following order:
@@ -25,23 +28,27 @@ The pipeline constructed by |charts| consists of the following segments in the f
 #. Maximum Document limit
 
 .. note::
-   You do not need to configure all of the above settings when creating a chart. Unspecified settings are skipped when 
-   generating the aggregation pipeline. 
+   You do not need to configure all of the above settings when creating
+   a chart. Unspecified settings are skipped when generating the
+   aggregation pipeline. 
 
 
 .. note::
-   Sorts and limits specified in the encoding panel are currently not included in the aggregation pipeline. Instead, the sorting and limiting is 
-   applied on the client-side while rendering the chart.
+   Sorts and limits specified in the encoding panel are currently not
+   included in the aggregation pipeline. Instead, the sorting and
+   limiting is applied on the client-side while rendering the chart.
 
 
 Example 
 -------
 
-The following chart shows the total sale amounts from an office supply company, categorized by 
-purchase method. Each document in the data collection represents a single sale.
+The following chart shows the total sale amounts from an office supply
+company, categorized by purchase method. Each document in the data
+collection represents a single sale.
 
-Using this chart as an example, we will explore how the specifications for each of the above settings change the 
-aggregation pipeline generated by |charts|. 
+Using this chart as an example, we will explore how the specifications
+for each of the above settings change the aggregation pipeline generated
+by |charts|. 
 
 .. figure:: /images/charts/agg-pipeline.png
    :figwidth: 720px
@@ -51,15 +58,15 @@ aggregation pipeline generated by |charts|.
 Encoding
 ~~~~~~~~
 
-Without any :guilabel:`Data Source` pipeline, :guilabel:`Query` bar queries, 
-calculated fields, and filters added in the :guilabel:`Filter` pane, |charts| generates the 
-following aggregation pipeline: 
+Without any :guilabel:`Data Source` pipeline, :guilabel:`Query` bar
+queries, calculated fields, and filters added in the :guilabel:`Filter`
+pane, |charts| generates the following aggregation pipeline: 
 
 .. code-block:: javascript
    :emphasize-lines: 1-31
 
    {
-     "$addFields": {                                     //Encoding
+     "$addFields": {                         //Encoding
        "__alias_0": {
          "$sum": "$items.price"
        }
@@ -94,8 +101,9 @@ following aggregation pipeline:
    }
 
 
-The pipeline at this stage only consists of groups from the :guilabel:`Encode` panel and the maximum
-document limit, which is set to 5000 by |charts|. 
+The pipeline at this stage only consists of groups from the
+:guilabel:`Encode` panel and the maximum document limit, which is set to
+5000 by |charts|. 
 
 Adding Queries
 ~~~~~~~~~~~~~~
@@ -121,7 +129,8 @@ Query:
  }
 
 
-Applying the above query in the :guilabel:`Query` bar generates the following chart and aggregation pipeline: 
+Applying the above query in the :guilabel:`Query` bar generates the
+following chart and aggregation pipeline: 
 
 .. figure:: /images/charts/agg-pipeline-query.png
    :figwidth: 720px
@@ -133,7 +142,7 @@ Aggregation Pipeline:
    :emphasize-lines: 1-18
 
    {
-     "$match": {                                                     //Query
+     "$match": {                              // Query
        "$and": [
          {
            "saleDate": {
@@ -185,16 +194,18 @@ Aggregation Pipeline:
    }
 
 
-The aggregation pipeline now starts with the query applied, and is followed by the groups selected in the 
-:guilabel:`Encode` panel and the max document limit. 
+The aggregation pipeline now starts with the query applied, and is
+followed by the groups selected in the :guilabel:`Encode` panel and the
+max document limit. 
 
 
 Adding Calculated Fields
 ~~~~~~~~~~~~~~~~~~~~~~~~
 
-We can also change the chart to show the total revenue generated categorized by 
-purchase method. To accomplish this task, we will create a calculated field that calculates 
-the total revenue by multiplying price by quantity. Adding this new calculated field, in addition to the 
+We can also change the chart to show the total revenue generated
+categorized by purchase method. To accomplish this task, we will create
+a calculated field that calculates the total revenue by multiplying
+price by quantity. Adding this new calculated field, in addition to the
 query above, produces the following chart and pipeline:
 
 
@@ -230,7 +241,7 @@ Aggregation Pipeline:
      }
    },
    {
-     "$addFields": {                                            //Calculated Field
+     "$addFields": {                          // Calculated Field
        "revenue": {
          "$reduce": {
            "input": "$items",
@@ -279,15 +290,18 @@ Aggregation Pipeline:
    }
 
 
-The updated pipeline now includes the calculated field right below the query applied in the :guilabel:`Query` bar while the order of 
-the rest of the components remains unchanged. 
+The updated pipeline now includes the calculated field right below the
+query applied in the :guilabel:`Query` bar while the order of the rest
+of the components remains unchanged. 
 
 
 Adding Filters
 ~~~~~~~~~~~~~~
 
-This chart can be further refined by adding a filter in the :guilabel:`Filter` pane to only select in-store sales made in the New York location. 
-Adding this filter produces the following chart and aggregation pipeline: 
+This chart can be further refined by adding a filter in the
+:guilabel:`Filter` pane to only select in-store sales made in the New
+York location. Adding this filter produces the following chart and
+aggregation pipeline: 
 
 .. figure:: /images/charts/agg-pipeline-with-filter.png
    :figwidth: 720px
@@ -339,7 +353,7 @@ Aggregation Pipeline:
      }
    },
    {
-     "$match": {                                                             // Filter
+     "$match": {                              // Filter
        "storeLocation": {
          "$nin": [
            null,
@@ -394,5 +408,6 @@ Aggregation Pipeline:
      "$limit": 5000
    }
 
-The pipeline now includes the storeLocation filter right below the calculated field while the order of 
-the rest of the components remains unchanged. 
+The pipeline now includes the ``storeLocation`` filter right below the
+calculated field while the order of the rest of the components remains
+unchanged. 

source/aggregation-pipeline.txt

@@ -6,6 +6,12 @@ Run Aggregation Pipelines on Your Data
 
 .. default-domain:: mongodb
 
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 1
+   :class: singlecol
+
 :manual:`Aggregation pipelines </core/aggregation-pipeline/>` transform
 your documents into an aggregated set of results. In |charts|,
 aggregation pipelines are commonly used to visualize new fields created

source/bin-data.txt

@@ -1,17 +1,23 @@
-.. _charts-bin-data:
-
-========
-Bin Data
-========
+==============================
+Bin, Sort, and Limit Your Data
+==============================
 
 .. default-domain:: mongodb
 
+You can bin, sort, and limit data in your charts to highlight key
+aspects in your data.
+
 .. contents:: On this page
    :local:
    :backlinks: none
    :depth: 1
    :class: singlecol
 
+.. _charts-bin-data:
+
+Bin Data
+--------
+
 |charts| supports *binning* both numeric and date fields in your
 data. Binning breaks continuous data into discrete groups called
 *bins*, with each bin containing a contiguous subset of the original
@@ -35,7 +41,7 @@ date.
 .. _bin-date-fields:
 
 Bin Date Fields
----------------
+~~~~~~~~~~~~~~~
 
 When handling dates, this data often comes in a continuous
 form. It can be useful to split this data into a specific windows of
@@ -120,7 +126,7 @@ visualization with no grouping performed.
       :alt: Charts binning by day example
 
 Bin Numeric Fields
-------------------
+~~~~~~~~~~~~~~~~~~
 
 |charts| can also bin numeric fields from a continuous set into groups
 of a specified size. This
@@ -160,7 +166,7 @@ to the visualization, rather than being grouped into bins.
       :alt: Charts numeric binning example
 
 Empty Bins
-----------
+~~~~~~~~~~
 
 When binning is enabled, |charts-short| displays entries for
 empty bins within the minimum and maximum data range a chart displays.
@@ -205,3 +211,53 @@ chart type:
      - Linear interpolation, with no data marker on the ``null`` bins.
        |charts-short| doesn't display data labels for ``null`` bins,
        even if enabled.
+
+.. _charts-sort-data:
+
+Sort Data
+---------
+
+By default, |charts-short| sorts data based on the :guilabel:`Value`
+field in descending order.
+
+Use the :guilabel:`Sort By` dropdown in the Chart Builder to sort by
+either the :guilabel:`Category` field or aggregated value.
+
+To toggle between ascending or descending sort order, click the ``a-z``
+button to the right of the :guilabel:`Sort By` dropdown.
+
+.. _charts-limit-data:
+
+Limit Data
+----------
+
+You can apply a limit to the :guilabel:`Category` encoding channel
+to only include a specified number of categories in your visualization.
+The categories included are the *first* matching categories based on
+the :ref:`sort order <charts-sort-data>` specified. Limiting data can
+be useful when visualizing data with so many categories it becomes
+difficult to create a meaningful chart.
+
+.. example::
+
+   The following chart shows the average
+   `IMDb <https://www.imdb.com/>`_ rating of movies from a
+   particular country:
+
+   .. figure:: /images/charts/charts-movie-ratings-by-country.png
+      :figwidth: 720px
+      :alt: Movie ratings by country
+
+   The dataset contains movies from many different countries, but it
+   would be most interesting to see which countries produce the
+   highest-rated movies. We can accomplish this by applying a limit to
+   only show countries with the 10 highest average ratings for movies.
+
+   Switch the :guilabel:`Limit Results` toggle to ``On`` and leave the
+   :guilabel:`Show` input at the default value of 10. The chart is now
+   much easier to understand, and we have a clear view of the countries
+   with the highest-rated movies:
+
+   .. figure:: /images/charts/charts-movie-ratings-by-country-limited.png
+      :figwidth: 720px
+      :alt: Movie ratings by country limited

source/build-charts-reference.txt

@@ -0,0 +1,22 @@
+.. _build-charts-reference:
+
+========================
+Chart Building Reference
+========================
+
+.. default-domain:: mongodb
+
+:ref:`charts-sample-mode`
+  Learn how |charts| samples data to improve rendering performance.
+
+:ref:`aggregation-pipeline-generation`
+  Learn how |charts| creates an aggregation pipeline based on your
+  chart configuration to render data.
+
+.. class:: hidden
+
+   .. toctree::
+      :titlesonly:
+
+      /sample-mode
+      /aggregation-pipeline-generation