【feat】产品页模块说明g6结构自动化; review by luox

Author: xiongjiaojiao

build/jsdocs/classic/docs.json

@@ -60,7 +60,7 @@
       "src/common/lang/locales"
     ]
   },
-  "plugins": ["plugins/markdown"],
+  "plugins": ["plugins/markdown", "../plugins/moduleCategories"],
   "templates": {
     "cleverLinks": false,
     "monospaceLinks": false,

build/jsdocs/leaflet/docs.json

@@ -77,7 +77,7 @@
             "src/leaflet/core/CommontypesConversion"
         ]
     },
-    "plugins": ["plugins/markdown","../plugins/usage"],
+    "plugins": ["plugins/markdown","../plugins/usage", "../plugins/moduleCategories"],
     "markdown": {
         "tags": ["usage"]
     },

build/jsdocs/mapboxgl/docs.json

@@ -67,7 +67,7 @@
             "src/mapboxgl/core/Util"
         ]
     },
-    "plugins": ["plugins/markdown","../plugins/usage"],
+    "plugins": ["plugins/markdown","../plugins/usage", "../plugins/moduleCategories"],
     "markdown": {
         "tags": ["usage"]
     },

build/jsdocs/maplibregl/docs.json

@@ -65,7 +65,7 @@
       "src/mapboxgl/core/Util"
     ]
   },
-  "plugins": ["plugins/markdown", "../plugins/usage"],
+  "plugins": ["plugins/markdown", "../plugins/usage", "../plugins/moduleCategories"],
   "markdown": {
     "tags": ["usage"]
   },

build/jsdocs/openlayers/docs.json

@@ -67,7 +67,7 @@
             "src/openlayers/core/Util"
         ]
     },
-    "plugins": ["plugins/markdown","../plugins/usage"],
+    "plugins": ["plugins/markdown","../plugins/usage", "../plugins/moduleCategories"],
     "markdown": {
         "tags": ["usage"]
     },

build/jsdocs/plugins/moduleCategories.js

@@ -0,0 +1,34 @@
+const env = require('jsdoc/lib/jsdoc/env');
+
+const globalParams =  env.conf.templates;
+exports.defineTags = function (dictionary) {
+  dictionary.defineTag('modulecategory', {
+    mustHaveValue: true,
+    mustNotHaveDescription: false,
+    canHaveType: false,
+    canHaveName: false,
+    onTagged: function (doclet, tag) {
+      doclet.modulecategory = {
+        globalParams,
+        category: tag.value,
+        name: doclet.name,
+        des_en: doclet.name
+      };
+    }
+  });
+};
+
+exports.handlers = {
+  newDoclet: function (e) {
+    const modulecategory = e.doclet.modulecategory;
+    if (modulecategory) {
+      e.doclet.modulecategory.className = modulecategory.name;
+      if (!modulecategory.name.startsWith('SuperMap')) {
+        const matchTag = e.doclet.tags.find(tag => tag.title === 'browsernamespace') || {};
+        const prefix = matchTag.value || globalParams.namespace;
+        e.doclet.modulecategory.name = `${prefix}.${modulecategory.name}`;
+      }
+      e.doclet.modulecategory.des = (e.doclet.classdesc || '').split('。')[0].replace('<p>', '').replace('类', '');
+    }
+  }
+};

build/jsdocs/template/module-categories.json

@@ -0,0 +1,31 @@
+{
+  "moduleRoots": {
+    "ol": "SuperMap iClient for OpenLayers",
+    "L": "SuperMap iClient for Leaflet",
+    "SuperMap": "SuperMap iClient Classic",
+    "mapboxgl": "SuperMap iClient for MapboxGL",
+    "maplibregl": "SuperMap iClient for MapLibreGL"
+  },
+  "moduleCategories": {
+    "Mapping": {
+      "des": "基础地图模块",
+      "des_en": "Basic map module"
+    },
+    "Services": {
+      "des": "服务模块",
+      "des_en": "Service module"
+    },
+    "Overlay": {
+      "des": "可视化与计算模块",
+      "des_en": "Visualization and calculation module"
+    },
+    "Control": {
+      "des": "功能控件模块",
+      "des_en": "Control module"
+    },
+    "Components": {
+      "des": "组件模块",
+      "des_en": "Component module"
+    }
+  }
+}

build/jsdocs/template/publish.js

@@ -8,6 +8,7 @@ var template = require('jsdoc/template'),
   helper = require('jsdoc/util/templateHelper'),
   logger = require('jsdoc/util/logger'),
   typeLinks = require('./typeLinkExt').typeLinks,
+  moduleCategoriesConfig = require('./module-categories.json'),
   _ = require('underscore'),
   htmlsafe = helper.htmlsafe,
   linkto = helper.linkto,
@@ -20,6 +21,7 @@ var template = require('jsdoc/template'),
   language,
   outdir = env.opts.destination;
 var util = require('util');
+var chalk = require('chalk');
 
 function find(spec) {
   return helper.find(data, spec);
@@ -259,7 +261,7 @@ function buildNav(members, view, templatePath) {
       }else{
         methods[element.fileName] = m;
       }
-      
+
     }
   }
   var methodsPath = path.join(outdir, 'methods.json');
@@ -298,6 +300,50 @@ function buildCategories(members, templatePath) {
   return categories;
 }
 
+function buildModuleCategories(data, outdir, conf) {
+  var clientModuleName = conf.namespace.replace('.supermap', '');
+  var moduleCategories = moduleCategoriesConfig.moduleCategories;
+  var rootDes = moduleCategoriesConfig.moduleRoots[clientModuleName];
+  var categories = Object.keys(moduleCategories).reduce((sum, key) => {
+    const info = moduleCategories[key];
+    sum[key] = {
+      name: key,
+      ...info,
+      children: []
+    }
+    return sum;
+  }, {});
+
+  data().each(function (v) {
+    var categoryInfo = v.modulecategory;
+    if (!categoryInfo) {
+      return;
+    }
+    if (!categories[categoryInfo.category]) {
+      console.log(chalk.red(`ERROR [${clientModuleName}]: The @modulecategory(${categoryInfo.category}) is not exsist in ${v.meta.filename}\n`));
+      return;
+    }
+    if (!categoryInfo.des) {
+      console.log(chalk.red(`ERROR [${clientModuleName}]: The @classdesc cannot be empty in ${v.meta.filename}\n`));
+    }
+    categories[categoryInfo.category].children.push({
+      name: categoryInfo.name,
+      des: categoryInfo.des,
+      des_en: categoryInfo.des_en,
+      docName: categoryInfo.className
+    });
+  });
+  const finalContent = {
+    id: clientModuleName,
+    name: rootDes,
+    des: rootDes,
+    children: Object.values(categories).filter(item => item.children.length > 0)
+  }
+  var outpath = path.join(outdir, 'module-categories.js');
+  fs.writeFileSync(outpath, `var deps = ${JSON.stringify(finalContent, null, 2)}`, 'utf8');
+  return categories;
+}
+
 /**
  * Create the navigation sidebar.
  * @param {object} members The members that will be used to create the sidebar.
@@ -1139,7 +1185,8 @@ exports.publish = function (taffyData, opts, tutorials) {
     const dir = outdir.replace('./docs/', '');
     return whiteLists[dir];
   }
-
+  // 生成产品介绍中模块说明的g6配置
+  buildModuleCategories(data, outdir, conf);
   const allFiles = getFileNames();
   console.error('生成的多余的文档页面: ', getMorePages(allFiles, getHtmlLinks(allFiles)));
   console.error('没有链接的类型: ', getWrongLink(allFiles));

build/pack.js

@@ -1,7 +1,6 @@
 const { Command } = require('commander');
 const program = new Command();
 var shell = require("shelljs");
-require("./deps");
 program.description('Customized pack iClient.');
 
 var excludeFields = ['title', 'description', 'description_en'];
@@ -70,4 +69,4 @@ function getCommonModulePaths() {
         })
     }
     return modulePaths;
-}
+}