This project is part of the source of The Apache ECharts Official Website. See echarts-website for more details of the building process.
Do not need other project.
npm run dev
It will:
To customize the links of echarts-examples and other configurations, you can create a local config file echarts-doc/config/env.dev-override.js, which is not tracked by git, and its top-level properties will be used to override the corresponding properties of echarts-doc/config/env.dev.js when npm run dev.
For example, create a echarts-doc/config/env.dev-override.js:
module.exports = { // These props will override the same props in `echarts-doc/config/env.dev.js` galleryViewPath: 'http://127.0.0.1:3002/en/view.html?local=1&c=', galleryEditorPath: 'http://127.0.0.1:3002/en/editor.html?local=1&c=', EMBEDDED_ECHARTS_SCRIPT_URL: 'http://localhost:8001/echarts/echarts/dist/echarts.js', };
“Since Version” is necessary in doc. Marking “since version” indicates when a new feature was introduced. For example,
{{ use: partial-version(version = "6.0.0") }}
{{ use: partial-version(version = ${version|minVersion('6.0.0')}) }}
That is, if the ${version} is empty or smaller than '6.0.0', use '6.0.0'.
Follow the version comparison rules in Semver 2.0 .
These global variables can be used in doc:
${galleryViewPath}: Use it like ${galleryViewPath}pie-legend.${galleryEditorPath}: Use it like ${galleryEditorPath}pie-legend.${optionDocPath}: Use it like ${optionDocPath}#xAxis.type.${apiDocPath}: Use it like ${apiDocPath}#echarts.init.${handbookPath}: Use it like ${handbookPath}basics/import.${websitePath}: Use it like ${websitePath}/examples/en/index.html#chart-type-custom.See samples in “Reference of echarts-examples or other links”
A ~ can be used to refer to a option item in the same doc. For example:
[xAxis.name](~xAxis.name)
To reference an anchor in different doc, it can be:
[itemStyle](option.html#series.itemStyle) [action.highlight](api.html#action.highlight) [Custom Series](tutorial.html#Custom%20Series) [Use ECharts with bundler and NPM](${handbookPath}basics/import)
To add references in a code block, we have to:
// See doc: ${optionDocPath}#series-bar.select // See doc: ${apiDocPath}#echarts.init
Embed an example in doc (display the example directly in doc with an iframe. To avoid performance issues, do not overuse it.):
~[700X300](${galleryViewPath}pie-legend&edit=1&reset=1) ~[700x300](${galleryViewPath}doc-example/aria-pie&edit=1&reset=1)
Insert an image:
[600xauto](~axis-align-with-label.png)
Provide an example link in doc:
[vertically scrollable legend](${galleryEditorPath}pie-legend&edit=1&reset=1) [aria pie](${galleryEditorPath}doc-example/aria-pie&edit=1&reset=1)
Provide a website link in doc:
[Apache ECharts website](${websitePath}/en/download.html)
// Good Some description {{ use: partial-xxx }} Some other description // Bad Some description about {{ use: partial-inline-xxx }}
Good: {{ if: ${prefix} !== '#' }} 表示同一层级的节点的颜色饱和度 选取范围。 {{ else }} 本系列默认的节点的颜色饱和度 选取范围。 {{ /if }} 数值范围 0 ~ 1。 Bad: {{ if: ${prefix} !== '#' }}表示同一层级的节点的{{ else }}本系列默认的{{ /if }} 颜色饱和度 选取范围。数值范围 0 ~ 1。 Good: {{ if: ${prefix} !== '#' }} It indicates the range of saturation (color alpha) for nodes in a level. {{ else }} It indicates the range of saturation (color alpha) for nodes of the series. {{ /if }} The range of values is 0 ~ 1. Bad: It indicates the range of saturation (color alpha) {{ if: ${prefix} !== '#' }}for nodes in a level {{ else }} of the series{{ /if }}. The range of values is 0 ~ 1.
Entries:
en/api/api.md, en/api/option.md, they will be compiled to webpage like api.html, option.htmlShared targets (text blocks):
partial folder, such as, en/api/partial/xxx, en/optino/partial/xxx, and named with a prefix partial-.Subtitles:
# series.bar(Object)
## propA(number|string) = null
some desc xxx
## propB(number|string) = null
some desc yyy
## propC(string) = ${defaultPropC|default("'auto'")}
#${prefix} someOtherProp(Object)
some desc zzz
(xxx|yyy) is the data type in that subtitle:number, string, boolean, Object, Array, Functionnumber|string.= xxx is the default value in that subtitle:null, undefined, true, false, 90 (a literal number), some literal string, [0, 90] (an literal array).= ${someVar}, = ${someVar|default(123)}, = ${someVar|default("'auto'")}.# series.bar(Object), the dot symbol represents a special meaning: the component main type is 'series' and the component sub-type is 'bar'.${prefix}${prefix} is like '#', '##', '###', ...When we define a "target" {{ target: partial-abc-1 }} #${prefix} propLayout(Object) All of the subtitles should uses that prefix variable. ##${prefix} x(number) some desc ##${prefix} y(number) some desc {{ /target }} {{ target: partial-target-2 }}
When we use that "partial-abc-1" {{ target: partial-def-2 }} #${prefix|default('#')} somePropA(Object) {{ use: partial-abc-1( prefix: ${prefix} + '#' ) }}
The template syntax follows etpl (but use {{ }} rather than <!-- --> as the interpolate tags).
A syntax highlight tool: etpl-vscode
Summary of the commonly used syntax:
--- TEMPLATE EXPRESSION --- The template syntax and expressions are encolsed by delimiters `{{` and `}}`. For example, {{ if: condition_expression }} xxx {{ /if }} The expressoin within `{{` and `}}` can be considered a (restricted) JS expression. For example, {{ if: ${someVar1} + 'abc' === '123abc' }} ... {{ /if }} {{ if: !${someVar2} }} ... {{ /if }} --- TEMPLATE VARIABLE --- Use a variable: some text ${someVariable} some text Variable scope: The scope of any variable is "target" (see below). Variable filter: Some predefined filters can be used in the template variable, e.g., ${someVariable|default("'auto'")} means using the string "'auto'" as the default if ${someVariable} is '' or null or undefined. Declaration or assignment of a target-local variable: {{ var: myVar = 'some' }} {{ var: myVar = 123 }} {{ var: myVar = ${someOtherStr} + 'some_str' }} NOTICE: Within a `{{` `}}` pair, DO NOT write {{ if: '${some}_abc' }}{{ /if }}. It should be {{ if: ${some} + '_abc' }}{{ /if }}, as the sentence within `{{` `}}` pair is treated like a normal JS expression. --- IF ELSE --- {{ if: ${number1} > 0 }} some text xxx {{ elif: ${string1} === 'abc' }} some text yyy {{ else }} some text zzz {{ /if }} Logical operators can be used in the conditional expression: {{ if: ${componentNameInLink} == null && ${seriesType} }} This componentNameInLink is null or undefined {{ var: componentNameInLink = 'series-' + ${seriesType} }} {{ /if }} --- FOR LOOP --- {{ for: ${persons} as ${person}, ${index} }} some text ${index}: ${person.name} {{ /for }} --- TARGET (DEFINE A TEXT BLOCK) --- {{ target: a_predefined_block_name_1 }} The input varA is ${varA} The input varB is ${varB} The input varC is ${varC} Notice: - The scope of the "target name" is the entire webpage (such as, `option.html`, `api.html`), so name conflicts should be avoided. - "target" is not shared across webpage (such as, `option.html`, `api.html`). - The close tag of "target" can be omitted, but not recommended. {{ /target }} --- USE (USE A PREDEFINED TEXT BLOCK) --- {{ use: a_predefined_block_name_1 }} {{ use: a_predefined_block_name_2( varA = ${myVarX}, varB = 123, varC = 'some string', prefix: ${prefix} + '##' ) }} Concatenation operator `+` can be used in that string.
This is the embedded example that can be opened by clicking “try it” and then appears on the right side of the doc page.
Declare the base echarts options (ExampleBaseOption), whose scope is each echarts component or series. A ExampleBaseOption can be shared by multiple options. e.g.,
<ExampleBaseOption name="cartesian-bar" title="直角坐标系上的柱状图" title-en="Bar on Cartesian"> const option = { ... } </ExampleBaseOption>
Declare example UI control in each option, who uses the currently opened example. Supported UI controls:
<ExampleUIControlBoolean default="true" /><ExampleUIControlNumber default="8" step="0.5" /><ExampleUIControlColor default="#d2dbee" /><ExampleUIControlEnum options="horizontal,vertical" default="horizontal" /><ExampleUIControlIcon default="none" /><ExampleUIControlVector default="0,0" /><ExampleUIControlAngle min="-90" max="90" step="1" /><ExampleUIControlPercent default="0" /><ExampleUIControlPercentVector min="0" dims="InnerStart,InnerEnd,OuterStart,OuterEnd" default="0,0,0,0" /><ExampleUIControlText />The detailed API and implementation of the UI controls can be checked in echarts-doc/src/controls/*.vue and echarts-doc/src/components/OptionControl.vue.
Note: currently ExampleBaseOption and ExampleUIControlXxx will be copied (by echarts-doc/build.js) from echarts-doc/zh/**/*.md to echarts-doc/en/**/*.md if they are not declared in echarts-doc/en/**/*.md.
Option docs needs to be formatted before commit.
Run
npm run format
Make sure have a double review on the git diff after formatted.
After you finished editing doc of one language. You can use following script to sync it to another language.
# zh to en node tool/patchLanguage --from=zh --to=en # en to zh node tool/patchLanguage --from=en --to=zh
Sync will move the structure. It will make editing of other languages much easier.
Again make sure have a double review on the git diff after syncing.