Merge pull request #766 from antvis/docs-rules

fix(ava/advisor): fix rule id & add explanation for rules used in advisor module

packages/ava/src/advisor/ruler/rules/index.ts

@@ -19,58 +19,68 @@ import { xAxisLineFading } from './x-axis-line-fading';
 
 import type { RuleModule } from '../types';
 
-/**
- * @public
- */
-export const CHART_RULE_ID = [
+/** hard rules for validating chart type */
+const HARD_RULE_ID = [
+  // table and kpi_panel not include currently
+  // 'aggregation-single-row',
+  // 'all-can-be-table',
   'data-check',
   'data-field-qty',
   'no-redundant-field',
   'purpose-check',
+];
+
+/** soft rules for scoring chart type */
+const SOFT_RULE_ID = [
   'series-qty-limit',
   'bar-series-qty',
-  'bar-without-axis-min',
   'line-field-time-ordinal',
   'landscape-or-portrait',
   'diff-pie-sector',
   'nominal-enum-combinatorial',
   'limit-series',
-  'aggregation-single-row',
-  'all-can-be-table',
-] as const;
+];
+
+/**
+ * @public
+ */
+export const CHART_RULE_ID = [...HARD_RULE_ID, ...SOFT_RULE_ID] as const;
 
 /**
  * @public
  */
-export type ChartRuleID = typeof CHART_RULE_ID[number];
+export type ChartRuleID = (typeof CHART_RULE_ID)[number];
 
 /**
  * @public
  */
-export const CHART_DESIGN_RULE_ID = ['x-axis-line-fading'] as const;
+export const CHART_DESIGN_RULE_ID = ['x-axis-line-fading', 'bar-without-axis-min'] as const;
 
 /**
  * @public
  */
-export type ChartDesignRuleID = typeof CHART_DESIGN_RULE_ID[number];
+export type ChartDesignRuleID = (typeof CHART_DESIGN_RULE_ID)[number];
 
 export type RuleId = ChartRuleID | ChartDesignRuleID;
 
 export const rules: Partial<Record<RuleId, RuleModule>> = {
+  /** -- hard rules -- */
   // table and kpi_panel not include currently
   // 'aggregation-single-row': aggregationSingleRow,
   // 'all-can-be-table': allCanBeTable,
-  'bar-series-qty': barSeriesQty,
-  'bar-without-axis-min': barWithoutAxisMin,
   'data-check': dataCheck,
   'data-field-qty': dataFieldQty,
+  'no-redundant-field': noRedundantField,
+  'purpose-check': purposeCheck,
+  /** -- soft rules -- */
+  'bar-series-qty': barSeriesQty,
   'diff-pie-sector': diffPieSector,
   'landscape-or-portrait': landscapeOrPortrait,
   'limit-series': limitSeries,
   'line-field-time-ordinal': lineFieldTimeOrdinal,
-  'no-redundant-field': noRedundantField,
   'nominal-enum-combinatorial': nominalEnumCombinatorial,
-  'purpose-check': purposeCheck,
   'series-qty-limit': seriesQtyLimit,
+  /** -- design rules -- */
   'x-axis-line-fading': xAxisLineFading,
+  'bar-without-axis-min': barWithoutAxisMin,
 };

site/.dumirc.ts

@@ -7,7 +7,7 @@ export default defineConfig({
     title: 'AVA',
     description: 'A framework and solution for more convenient visual analytics.',
     defaultLanguage: 'zh',
-    siteUrl: homepage,
+    siteUrl: 'https://antv.antgroup.com/', // AntV 主站首页地址
     isAntVSite: false,
     githubUrl: repository.url,
     footerTheme: 'light', // 白色 底部主题

site/docs/api/advice/Ruler.en.md

@@ -165,8 +165,6 @@ const ChartRuleID = [
   'diff-pie-sector',
   'nominal-enum-combinatorial',
   'limit-series',
-  'aggregation-single-row',
-  'all-can-be-table',
 ];
 ```
 
@@ -175,7 +173,7 @@ const ChartRuleID = [
 * **Interface** *
 
 ```ts
-const ChartDesignRuleID = ['x-axis-line-fading'];
+const ChartDesignRuleID = ['x-axis-line-fading', 'bar-without-axis-min'];
 ```
 
 ## ChartRuleConfig

site/docs/api/advice/Ruler.zh.md

@@ -161,8 +161,6 @@ const ChartRuleID = [
   'diff-pie-sector',
   'nominal-enum-combinatorial',
   'limit-series',
-  'aggregation-single-row',
-  'all-can-be-table',
 ];
 ```
 
@@ -171,7 +169,7 @@ const ChartRuleID = [
 * **接口描述** *
 
 ```ts
-const ChartDesignRuleID = ['x-axis-line-fading'];
+const ChartDesignRuleID = ['x-axis-line-fading', 'bar-without-axis-min'];
 ```
 
 ## ChartRuleConfig

site/docs/guide/advice/rules.en.md

@@ -5,26 +5,62 @@ order: 1
 
 <embed src='@/docs/common/style.md'></embed>
 <!-- omit in toc -->
+
+## Introduction
+
+`advisor` module is based on rules for chart recommendation and optimization, divided into three main categories of rules:
+1. Hard Rules: Rules that must be satisfied, and if the chart type cannot satisfy any of the rules in the hard rule set, it will not appear in the final list of recommended charts.
+2. Soft Rules: Rules that are recommended to be satisfied, used for scoring charts and giving suggestions, the higher the score, the more suitable it is to use the corresponding chart type.
+3. Design Rules: Rules for optimizing the chart spec.
+
+By default, the chart recommendation rules are used built-in recommendation rules for chart recommendation, and in addition, rules can be switched, configured, and customized with users' own rules.
+```js
+// custom rule Config
+const myRuleCfg = {
+  // not use data-field-qty rule
+  exclude: ['limit-series'],
+  // add a custom rule
+  custom: {
+    'no-line-chart-with-year': myRule,
+  },
+  options: {
+    // customize rule options
+    'diff-pie-sector': {
+      weight: 0.8
+    }
+  }
+};
+
+const myAdvisor = new Advisor({ ruleCfg: myRuleCfg });
+```
+
+Details of `ruler` module can be found in：[Ruler API](../../api/advice/Ruler.zh.md)。
+
 ## Rules List
 
-* [General Rules](#general-rules)
-  * [data-check](#data-check)
-  * [data-field-qty](#data-field-qty)
-  * [no-redundant-field](#no-redundant-field)
-  * [purpose-check](#purpose-check)
-  * [bar-series-qty](#bar-series-qty)
-  * [diff-pie-sector](#diff-pie-sector)
-  * [landscape-or-portrait](#landscape-or-portrait)
-  * [limit-series](#limit-series)
-  * [line-field-time-ordinal](#line-field-time-ordinal)
-  * [nominal-enum-combinatorial](#nominal-enum-combinatorial)
-  * [series-qty-limit](#series-qty-limit)
-  * [bar-without-axis-min](#bar-without-axis-min)
-  * [x-axis-line-fading](#x-axis-line-fading)
-
-## General Rules
+* [Hard Rules](#hard-rules)
+  * [data-check](#data-check): Having the minimum set of data fields necessary for a given chart type
+  * [data-field-qty](#data-field-qty): Data must have at least the min qty of the prerequisite.
+  * [no-redundant-field](#no-redundant-field): All fields should be assigned to a visual mapping.
+  * [purpose-check](#purpose-check): Choose chart types that satisfy the purpose, if purpose is defined.
+* [Soft Rules](#soft-rules)
+  * [bar-series-qty](#bar-series-qty): A Bar chart should has proper number of bars or bar groups.
+  * [diff-pie-sector](#diff-pie-sector): The difference between sectors of a pie chart should be large enough.
+  * [landscape-or-portrait](#landscape-or-portrait): 
+Recommend column charts for landscape layout and bar charts for portrait layout.
+  * [limit-series](#limit-series): Avoid too many values in one series.
+  * [line-field-time-ordinal](#line-field-time-ordinal): Data containing time or ordinal fields are suitable for line or area charts.
+  * [nominal-enum-combinatorial](#nominal-enum-combinatorial): Basic (column, bar) charts or grouped (or stacked) charts are recommended based on the repetition of dimension values.
+  * [series-qty-limit](#series-qty-limit): Some charts should has at most N values for the series.
+* [Design Rules](#design-rules)
+  * [bar-without-axis-min](#bar-without-axis-min): The measure axis of a bar chart or column chart should start with zero.
+  * [x-axis-line-fading](#x-axis-line-fading): The value range of the y-axis of the line graph should be set in a reasonable range.
+
 
 <!-- ****************************** Hard Rules ****************************** -->
+## Hard Rules
+
+Hard rules are used to determine whether input data can be drawn using the given chart type. If any of hard rules is not met, the score of the given chart type will be 0, meaning that chart type will not appear in the advisor's recommended chart list.
 
 ### data-check
 
@@ -42,7 +78,7 @@ To be able to plot a certain type of chart, you must have at least the minimum s
 <!-- omit in toc -->
 #### Rule Details
 
-Each chart type has its own minimum set of necessary data fields. For example, to plot a bar chart, there must be at least two fields: a nominal field as a dimension, displayed on the x-axis, and a quantitative field as a measure, displayed on the y-axis. When we provide a dataset that does not meet this criterion, for example, with only two nominal fields, it is obviously impossible to draw a bar chart. This rule verifies that the input dataset meets the minimum set of data fields required for each chart type.
+Each chart type has its own minimum set of necessary data fields. For example, to plot a bar chart, there must be at least two fields: a nominal field as a dimension, displayed on the x-axis, and a quantitative field as a measure, displayed on the y-axis. When we provide a dataset that does not meet this criterion, for example, with only two nominal fields, it is obviously impossible to draw a bar chart. This rule verifies that the input dataset meets the minimum set of data fields required for each chart type. The required conditions of the fields for each chart type are from the `dataPres` property in `ckb`, and you can also go to [this link](https://www.yuque.com/antv/ava/cvv8u6fg7i7oqdak) to look through the field requirements for each chart.
 
 <!-- omit in toc -->
 #### Resources
@@ -152,6 +188,10 @@ The specific analysis purposes and the analysis purposes that each chart type ca
 
 <!-- ****************************** Soft Rules ****************************** -->
 
+## Soft Rules
+
+Soft rules are used to score the given chart type and provide suggestions based on the input data. The higher the score, the corresponding chart type is more suitable for the input data.
+
 ### bar-series-qty
 
 A Bar chart should has proper number of bars or bar groups.
@@ -383,6 +423,9 @@ Some charts like pie charts, radar charts, where there will be a dimension as a
 <!-- ============================================================================== -->
 
 <!-- ****************************** Design Rules ****************************** -->
+## Design Rules
+
+The design rules are applied to improve the existing chart specs, for example, adjusting axis scale config.
 
 ### bar-without-axis-min
 

site/docs/guide/advice/rules.zh.md

@@ -5,26 +5,62 @@ order: 1
 
 <embed src='@/docs/common/style.md'></embed>
 <!-- omit in toc -->
+
+## 规则模块介绍
+
+advisor 模块基于规则进行图表推荐和优化，分为三大类规则：
+1. 强规则（Hard Rules）：必须满足的规则，如果图表类型不能满足强规则集中的任何一条，则不会出现在最终推荐图表列表中。
+2. 弱规则（Soft Rules）：建议满足的规则，用于对图表类型进行打分和给出建议，得分越高表明越适合用相应的图表类型。
+3. 设计规则（Design Rules）：图表 spec 优化规则，用于对产生的图表 spec 进行优化。
+
+默认使用[内置推荐规则](#推荐规则一览)进行图表推荐，除此之外，还可以对规则进行开关、配置和定制自己的规则：
+```js
+// custom rule Config
+const myRuleCfg = {
+  // not use data-field-qty rule
+  exclude: ['limit-series'],
+  // add a custom rule
+  custom: {
+    'no-line-chart-with-year': myRule,
+  },
+  options: {
+    // customize rule options
+    'diff-pie-sector': {
+      weight: 0.8
+    }
+  }
+};
+
+const myAdvisor = new Advisor({ ruleCfg: myRuleCfg });
+```
+
+规则模块的详细用法可参考：[Ruler API](../../api/advice/Ruler.zh.md)。
+
 ## 推荐规则一览
 
-* [通用规则](#通用规则)
-  * [data-check](#data-check)
-  * [data-field-qty](#data-field-qty)
-  * [no-redundant-field](#no-redundant-field)
-  * [purpose-check](#purpose-check)
-  * [bar-series-qty](#bar-series-qty)
-  * [diff-pie-sector](#diff-pie-sector)
-  * [landscape-or-portrait](#landscape-or-portrait)
-  * [limit-series](#limit-series)
-  * [line-field-time-ordinal](#line-field-time-ordinal)
-  * [nominal-enum-combinatorial](#nominal-enum-combinatorial)
-  * [series-qty-limit](#series-qty-limit)
-  * [bar-without-axis-min](#bar-without-axis-min)
-  * [x-axis-line-fading](#x-axis-line-fading)
-
-## 通用规则
+下面展示了所有的内置规则，可以点击查看相应规则的详细解释。
+
+* [强规则 Hard rules](#强规则)
+  * [data-check](#data-check): 数据字段是否满足相应图表类型绘制所需的要求
+  * [data-field-qty](#data-field-qty): 字段数量不少于图表所需的最小字段数量
+  * [no-redundant-field](#no-redundant-field): 每个字段在图表绘制中都需要被用上
+  * [purpose-check](#purpose-check): 如果指定了分析目的类型，只推荐能服务于这种分析目的的图表类型
+* [弱规则 Soft rules](#弱规则)
+  * [bar-series-qty](#bar-series-qty): 条形图应该具有恰当数量的条形或条形组
+  * [diff-pie-sector](#diff-pie-sector): 饼图各扇区之间应该有足够大的差异
+  * [landscape-or-portrait](#landscape-or-portrait): 竖向画布更推荐使用条形图，横向画布更推荐使用柱状图
+  * [limit-series](#limit-series): 避免一种序列的值过多
+  * [line-field-time-ordinal](#line-field-time-ordinal): 包含时间或顺序性字段的数据适合用折线图或面积图来展示
+  * [nominal-enum-combinatorial](#nominal-enum-combinatorial): 根据维值的重复性来推荐基础图表或分组图表
+  * [series-qty-limit](#series-qty-limit): 一些图表类型中的序列的值不能太多
+* [设计规则 Design rules](#设计规则)
+  * [bar-without-axis-min](#bar-without-axis-min): 柱状图或条形图的数值轴的刻度应该从零开始
+  * [x-axis-line-fading](#x-axis-line-fading): 图表值域应该设置在一个合理的范围
 
 <!-- ****************************** Hard Rules ****************************** -->
+## 强规则
+
+强规则用于判断输入数据是否能使用给定的图表类型绘制，不满足时，给定图表类型得分将为 0，即不满足强规则的图表类型不会出现在 advisor 推荐的图表列表中。
 
 ### data-check
 
@@ -42,7 +78,7 @@ order: 1
 <!-- omit in toc -->
 #### 详细解释
 
-每种图表类型都有自己必需的最小数据字段集合。比如要绘制一个柱状图，最少要有两个字段：一个名词型字段当做维度，展示在 x 轴；一个数值型字段当做度量，展示在 y 轴。当我们提供的数据集不符合这个标准，比如只有两个名词型字段，显然是无法绘制出一个柱状图的。本规则验证输入的数据集是否满足每一种图表类型的最小数据字段集合要求。
+每种图表类型都有自己必需的最小数据字段集合。比如要绘制一个柱状图，最少要有两个字段：一个名词型字段当做维度，展示在 x 轴；一个数值型字段当做度量，展示在 y 轴。当我们提供的数据集不符合这个标准，比如只有两个名词型字段，显然是无法绘制出一个柱状图的。本规则验证输入的数据集是否满足每一种图表类型的最小数据字段集合要求。每种图表类型所需的字段要求校验条件来自于 `ckb` 中图表对应的 `dataPres` 属性，也可以通过[图表所需的字段一览](https://www.yuque.com/antv/ava/cvv8u6fg7i7oqdak)快速查阅。
 
 <!-- omit in toc -->
 #### 相关链接
@@ -151,6 +187,9 @@ order: 1
 <!-- ============================================================================== -->
 
 <!-- ****************************** Soft Rules ****************************** -->
+## 弱规则
+
+弱规则用于根据输入数据为给定的图表类型打分和给出建议，得分越高表明越适合用相应的图表类型。
 
 ### bar-series-qty
 
@@ -382,6 +421,9 @@ order: 1
 <!-- ============================================================================== -->
 
 <!-- ****************************** Design Rules ****************************** -->
+## 设计规则
+
+设计规则用于优化已有的图表 spec ，例如调整坐标轴的 scale 配置。
 
 ### bar-without-axis-min