(echarts-examples) 05/10: infra: (1) Rename 'excludeFromGallery' to 'noExplore'. (2) Support metadata in doc-example/xxx .

[su...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

sushuang pushed a commit to branch v6-examples-supplement
in repository https://gitbox.apache.org/repos/asf/echarts-examples.git

commit f2e66f25f4e7cb843d231e1ea5dc0d3f70436a1c
Author: 100pah <su...@gmail.com>
AuthorDate: Thu Aug 7 04:40:03 2025 +0800

    infra: (1) Rename 'excludeFromGallery' to 'noExplore'. (2) Support metadata in doc-example/xxx .
---
 README.md               |   8 +--
 src/explore/Explore.vue |   3 +
 tool/build-example.js   | 170 ++++++++++++++++++++++++++----------------------
 3 files changed, 101 insertions(+), 80 deletions(-)

diff --git a/README.md b/README.md
index 0b3bef9b..19a267df 100644
--- a/README.md
+++ b/README.md
@@ -40,20 +40,20 @@ since: 6.0.0
 
 Note:
 - The metadata, i.e., the first JavaScript comment block, will be removed when displaying the source code in editor page.
-- If you want the example to be included in the [example gallery page](https://echarts.apache.org/examples/en/index.html)
+- If you want the example to be included in the [example exploration page](https://echarts.apache.org/examples/en/index.html)
   - metadata properies `title` and `category` must be provided.
-  - must no `excludeFromGallery: true`.
+  - must no `noExplore: true`.
   - The example should under `public/examples/ts/` folder directly, rather than in folder `public/examples/ts/doc-example/`.
 - **Do not modify the file path of existing examples**, unless you search and update all the links in `echarts-doc` correspondingly.
 
 Metadata properties can be:
 + `title`: Optional. String.
 + `titleCN`: Optional. String.
-+ `category`: Optional. String list. That is the main categories in [example gallery page](https://echarts.apache.org/examples/en/index.html). If multiple categories need to be specified, use quotation marks and commas like `/* category: 'line, visualMap' */`
++ `category`: Optional. String list. That is the main categories in [example exploration page](https://echarts.apache.org/examples/en/index.html). If multiple categories need to be specified, use quotation marks and commas like `/* category: 'line, visualMap' */`
 + `since`: Optional. Semver version string. Recommended to add it to hint users the available echarts versions. For example, `/* since: 6.0.0 */`. Do not use `v6.0.0`, must follow Semver format.
 + `difficulty`: Optional. Number.
 + `theme`: Optional. String.
-+ `excludeFromGallery`: Optional. Boolean. Indicate that exclude this example from [example gallery page](https://echarts.apache.org/examples/en/index.html).
++ `noExplore`: Optional. Boolean. Indicate that exclude this example from [example exploration page](https://echarts.apache.org/examples/en/index.html).
 + `videoStart` and `videoEnd`: Optional. Number. Record a video to show the animation when genering screenshot. For example,
   ```js
   /*
diff --git a/src/explore/Explore.vue b/src/explore/Explore.vue
index 2f9902b9..cb3c36e4 100644
--- a/src/explore/Explore.vue
+++ b/src/explore/Explore.vue
@@ -146,6 +146,9 @@ export default {
           if (BLACK_MAP.hasOwnProperty(example.id)) {
             continue;
           }
+          if (example.noExplore) {
+            continue;
+          }
           if (typeof example.category === 'string') {
             example.category = [example.category];
           }
diff --git a/tool/build-example.js b/tool/build-example.js
index 321ac327..362f506e 100644
--- a/tool/build-example.js
+++ b/tool/build-example.js
@@ -14,6 +14,7 @@ const { compareImage } = require('../common/compareImage');
 const { runTasks } = require('../common/task');
 const nStatic = require('node-static');
 const shell = require('shelljs');
+const assert = require('assert');
 
 function optionToJson(obj, prop) {
   let json = JSON.stringify(
@@ -275,96 +276,113 @@ async function takeScreenshot(
   let server; // Declare server at function scope
 
   const examplesRoot = `${rootDir}public/examples`;
-  const files = await globby(`js/${isGL ? 'gl/' : ''}*.js`, {
+  const filesPrimary = await globby(`js/${isGL ? 'gl/' : ''}*.js`, {
+    cwd: examplesRoot,
+    absolute: true
+  });
+  const filesInDocExampleFolder = isGL ? [] : await globby(`js/doc-example/*.js`, {
     cwd: examplesRoot,
     absolute: true
   });
 
   const exampleList = [];
+  const thumbTasks = [];
 
-  let thumbTasks = [];
-
-  for (let theme of themeList) {
-    for (let fileName of files) {
-      const basename = path.basename(fileName, '.js');
-
-      // Remove mapbox temporary
-      if (
-        basename.indexOf('mapbox') >= 0 ||
-        basename.indexOf('shanghai') >= 0 ||
-        basename === 'lines3d-taxi-routes-of-cape-town' ||
-        basename === 'lines3d-taxi-chengdu' ||
-        basename === 'map3d-colorful-cities' ||
-        // TODO Examples that can't work temporary.
-        basename === 'bar3d-music-visualization'
-      ) {
-        continue;
-      }
+  for (const theme of themeList) {
+    for (const fileAbsPath of filesPrimary) {
+      handleSingleFile(fileAbsPath, theme, false);
+    }
+  }
+  for (const fileAbsPath of filesInDocExampleFolder) {
+    handleSingleFile(fileAbsPath, null, true);
+  }
 
-      const tsFile = `${examplesRoot}/ts/${isGL ? 'gl/' : ''}${basename}.ts`;
-      const hasTs = fs.existsSync(tsFile);
+  function handleSingleFile(fileAbsPath, thumbTheme, noThumb) {
+    const relativePath = path.relative(path.join(examplesRoot, 'js'), fileAbsPath);
+    assert(relativePath !== '' && relativePath.indexOf('.') !== 0 && !path.isAbsolute(relativePath));
+    const exampleId = relativePath.replace(/\.js$/, '');
+
+    // Remove mapbox temporary
+    if (
+      exampleId.indexOf('mapbox') >= 0 ||
+      exampleId.indexOf('shanghai') >= 0 ||
+      exampleId === 'lines3d-taxi-routes-of-cape-town' ||
+      exampleId === 'lines3d-taxi-chengdu' ||
+      exampleId === 'map3d-colorful-cities' ||
+      // TODO Examples that can't work temporary.
+      exampleId === 'bar3d-music-visualization'
+    ) {
+      return;
+    }
 
-      let fmResult;
-      try {
-        const code = fs.readFileSync(fileName, 'utf-8');
-        fmResult = matter(code, {
-          delimiters: ['/*', '*/']
-        });
-      } catch (e) {
-        fmResult = {
-          data: {}
-        };
-      }
+    const tsFile = path.normalize(`${examplesRoot}/ts/${isGL ? 'gl/' : ''}${exampleId}.ts`);
+    const hasTs = fs.existsSync(tsFile);
 
-      if (fmResult.data.excludeFromGallery) {
-        // `fmResult.data.excludeFromGallery` is boolean if writing `/* excludeFromGallery: true */` in code.
-        continue;
-      }
+    let fmResult;
+    try {
+      const code = fs.readFileSync(fileAbsPath, 'utf-8');
+      fmResult = matter(code, {
+        delimiters: ['/*', '*/']
+      });
+    } catch (e) {
+      fmResult = {
+        data: {}
+      };
+    }
 
-      try {
-        const difficulty =
-          fmResult.data.difficulty != null ? fmResult.data.difficulty : 10;
-        const category = (fmResult.data.category || '')
-          .split(/,/g)
-          .map((a) => a.trim())
-          .filter((a) => !!a);
-
-        if (!exampleList.find((item) => item.id === basename)) {
-          // Avoid add multiple times when has multiple themes.
-          exampleList.push({
-            category: category,
-            id: basename,
-            ts: hasTs,
-            tags: (fmResult.data.tags || '')
-              .split(/,/g)
-              .map((a) => a.trim())
-              .filter((a) => !!a),
-            theme: fmResult.data.theme,
-            title: fmResult.data.title,
-            titleCN: fmResult.data.titleCN,
-            difficulty: +difficulty,
-            since: fmResult.data.since,
-          });
-        }
-      } catch (e) {
-        throw new Error(e.toString());
-      }
+    // `fmResult.data.noExplore` is boolean if writing `/* noExplore: true */` in code.
+    const noExplore = fmResult.data.noExplore;
 
-      if (
-        !matchPattern ||
-        (matchPattern.some(function (pattern) {
-          return minimatch(basename, pattern);
-        }) &&
-          screenshotBlackList.indexOf(basename) < 0)
-      ) {
-        thumbTasks.push({
-          theme,
-          fmResult,
-          basename
+    try {
+      const difficulty =
+        fmResult.data.difficulty != null ? fmResult.data.difficulty : 10;
+      const category = (fmResult.data.category || '')
+        .split(/,/g)
+        .map((a) => a.trim())
+        .filter((a) => !!a);
+
+      if (!exampleList.find((item) => item.id === exampleId)) {
+        // Avoid add multiple times when has multiple themes.
+        exampleList.push({
+          category: category,
+          id: exampleId,
+          ts: hasTs,
+          tags: (fmResult.data.tags || '')
+            .split(/,/g)
+            .map((a) => a.trim())
+            .filter((a) => !!a),
+          noExplore: noExplore,
+          theme: fmResult.data.theme,
+          title: fmResult.data.title,
+          titleCN: fmResult.data.titleCN,
+          difficulty: +difficulty,
+          since: fmResult.data.since,
         });
       }
+    } catch (e) {
+      throw new Error(e.toString());
     }
-  }
+
+    if (
+      !noThumb
+      && !noExplore
+      && (
+        !matchPattern
+        || (
+          matchPattern.some(function (pattern) {
+            return minimatch(exampleId, pattern);
+          })
+          && screenshotBlackList.indexOf(exampleId) < 0
+        )
+      )
+    ) {
+      thumbTasks.push({
+        thumbTheme,
+        fmResult,
+        exampleId
+      });
+    }
+  } // End of handleSingleFile
 
   exampleList.sort(function (a, b) {
     if (a.difficulty === b.difficulty) {


---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@echarts.apache.org
For additional commands, e-mail: commits-help@echarts.apache.org