diff --git a/.gitignore b/.gitignore index d94a7b0..c852e54 100644 --- a/.gitignore +++ b/.gitignore @@ -1,3 +1,4 @@ +*.tsbuildinfo ._* .DS_Store /npm-debug.log diff --git a/.vscode/settings.json b/.vscode/settings.json new file mode 100644 index 0000000..55712c1 --- /dev/null +++ b/.vscode/settings.json @@ -0,0 +1,3 @@ +{ + "typescript.tsdk": "node_modules/typescript/lib" +} \ No newline at end of file diff --git a/README.md b/README.md index 3b1b0b2..17fa52e 100644 --- a/README.md +++ b/README.md @@ -53,11 +53,23 @@ gulp.src(sourceFiles, { read: false }) ``` + +Parser +====== + +This new parser creates an AST of source files. The AST containes classes and +options. Every source file ending on `Options` is treated as part of the option +tree. Every source file ending on `Defaults` is treated as a complementary to +options. + + + TypeDoc ======= -The generator is not ready yet. It contains a handlebars template system and -library scripts to generate future documentation out of TypeScript source code. +The generator is used for internal documentation of Highcharts. It contains a +handlebars template system and library scripts to generate documentation out of +TypeScript source code. See the included [readme](https://github.com/highcharts/highcharts-documentation-generators/blob/master/typedoc/README.md) for development information. diff --git a/api-docs/lib/index.js b/api-docs/lib/index.js index 9d81016..3ebc5b2 100644 --- a/api-docs/lib/index.js +++ b/api-docs/lib/index.js @@ -128,20 +128,6 @@ function mergeObj(a, b, ignoreEmpty, excludeMap, noOverwrite) { return a; } -function getExcludeMap(node) { - var map = {}; - - ((node && node.doclet && node.doclet.tags) || []).forEach(function (tag) { - if (tag.title === 'excluding' || tag.title === 'exclude') { - tag.value.split(',').forEach(function (p) { - map[p.trim()] = true; - }); - } - }); - - return map; -} - function getSearchBoost(optionPath) { if (!optionPath) { @@ -691,22 +677,6 @@ module.exports = function (input, outputPath, selectedProducts, fn) { } } - // Extract array type - function extractArrayType(def) { - var s = def.indexOf('<'), - s2 = def.indexOf('>'), - res - ; - - if (s >= 0 && s2 >= 0) { - res = def.substr(s + 1, s2 - s - 1); - - return res; - } - - return 'object'; - } - // Do some transformations function transform(name, node, parentName, parent) { var s, v = false; @@ -799,7 +769,10 @@ module.exports = function (input, outputPath, selectedProducts, fn) { !node.doclet.type ) { let defaultvalueForType = node.doclet.defaultvalue; - if (typeof node.meta.default !== 'undefined' && typeof node.doclet.defaultvalue === 'undefined') { + if ( + typeof node.meta.default !== 'undefined' && + typeof node.doclet.defaultvalue === 'undefined' + ) { defaultvalueForType = node.meta.default; } @@ -998,33 +971,6 @@ module.exports = function (input, outputPath, selectedProducts, fn) { } - function templateize(name) { - // Enable this to use e.g. series rather than series.type - return name; - - name = name || ''; - - if (name.indexOf('<') > 0) { - return name; - } - - if ( - name.indexOf('series') === 0 && - name.indexOf('.') >= 0 - ) { - - name = name.replace(/\./, '<'); - - if (name.indexOf('.') > 0) { - name = name.replace(/\./, '>.'); - } else { - name += '>'; - } - } - - return name; - } - function dumpNav(node, opath, product, version) { opath += 'nav/'; @@ -1032,10 +978,6 @@ module.exports = function (input, outputPath, selectedProducts, fn) { return; } - if (node.meta && node.meta.fullname) { - node.meta.fullname = templateize(node.meta.fullname); - } - fs.writeFileSync( opath + (node.meta.fullname || 'index') + '.json', JSON.stringify({ @@ -1073,7 +1015,6 @@ module.exports = function (input, outputPath, selectedProducts, fn) { } function generateDetails(name, node, opath, product, version, toc, constr) { - name = templateize(name); version = (version === 'current' ? versionProps.version : version); // work around #8260: @@ -1081,10 +1022,6 @@ module.exports = function (input, outputPath, selectedProducts, fn) { return; } - if (node.meta && node.meta.fullname) { - node.meta.fullname = templateize(node.meta.fullname); - } - // merge(node, node.meta.fullname); if (!node.children) { diff --git a/generator/build/JSON.d.ts b/generator/build/JSON.d.ts new file mode 100644 index 0000000..dcbb2eb --- /dev/null +++ b/generator/build/JSON.d.ts @@ -0,0 +1,33 @@ +/*!* + * + * Copyright (C) Highsoft AS + * + * */ +export declare namespace JSON { + type Array = globalThis.Array<(Collection | Primitive)>; + type Collection = (Array | Object); + interface Object extends Record { + [key: string]: (Collection | Primitive); + } + type Primitive = (bigint | boolean | null | number | string | undefined); + interface PrimitiveMap { + bigint: bigint; + boolean: boolean; + null: null; + number: number; + string: string; + undefined: undefined; + } + const parse: (text: string, reviver?: ((this: any, key: string, value: any) => any) | undefined) => any; + /** + * Retrieves a value as a specific primitive type and falls back to a + * default value, if not successfull. + */ + function get(type: T, value: unknown, defaultValue: PrimitiveMap[T]): PrimitiveMap[T]; + /** + * Converts a JavaScript object to JSON notation and filters circular + * references by removing them. + */ + function stringify(obj: unknown): string; +} +export default JSON; diff --git a/generator/build/JSON.js b/generator/build/JSON.js new file mode 100644 index 0000000..b8c1111 --- /dev/null +++ b/generator/build/JSON.js @@ -0,0 +1,74 @@ +"use strict"; +/*!* + * + * Copyright (C) Highsoft AS + * + * */ +Object.defineProperty(exports, "__esModule", { value: true }); +exports.JSON = void 0; +/* * + * + * Namespace + * + * */ +var JSON; +(function (JSON) { + /* * + * + * Declarations + * + * */ + /* * + * + * Constants + * + * */ + JSON.parse = global.JSON.parse; + /* * + * + * Functions + * + * */ + /** + * Retrieves a value as a specific primitive type and falls back to a + * default value, if not successfull. + */ + function get(type, value, defaultValue) { + if (typeof value === type) { + return value; + } + else { + return defaultValue; + } + } + JSON.get = get; + /** + * Converts a JavaScript object to JSON notation and filters circular + * references by removing them. + */ + function stringify(obj) { + const references = []; + return globalThis.JSON.stringify(obj, (_key, item) => { + if (typeof item === 'object' && + item) { + if (references.includes(item) || + item instanceof Array && + !item.length) { + return void 0; + } + else { + references.push(item); + } + } + return item; + }, '\t'); + } + JSON.stringify = stringify; +})(JSON = exports.JSON || (exports.JSON = {})); +/* * + * + * Default Export + * + * */ +exports.default = JSON; +//# sourceMappingURL=JSON.js.map \ No newline at end of file diff --git a/generator/build/JSON.js.map b/generator/build/JSON.js.map new file mode 100644 index 0000000..77a19d0 --- /dev/null +++ b/generator/build/JSON.js.map @@ -0,0 +1 @@ +{"version":3,"file":"JSON.js","sourceRoot":"","sources":["../sources/JSON.ts"],"names":[],"mappings":";AAAA;;;;KAIK;;;AAEL;;;;KAIK;AAEL,IAAiB,IAAI,CA0FpB;AA1FD,WAAiB,IAAI;IAEjB;;;;SAIK;IAqBL;;;;SAIK;IAEQ,UAAK,GAAG,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC;IAEvC;;;;SAIK;IAEL;;;OAGG;IACH,SAAgB,GAAG,CACf,IAAO,EACP,KAAc,EACd,YAA6B;QAE7B,IAAI,OAAO,KAAK,KAAK,IAAI,EAAE;YACvB,OAAO,KAAwB,CAAC;SACnC;aAAM;YACH,OAAO,YAAY,CAAC;SACvB;IACL,CAAC;IAVe,QAAG,MAUlB,CAAA;IAED;;;OAGG;IACH,SAAgB,SAAS,CACrB,GAAY;QAEZ,MAAM,UAAU,GAA8B,EAAE,CAAC;QAEjD,OAAO,UAAU,CAAC,IAAI,CAAC,SAAS,CAC5B,GAAG,EACH,CAAC,IAAY,EAAE,IAAa,EAAW,EAAE;YACrC,IACI,OAAO,IAAI,KAAK,QAAQ;gBACxB,IAAI,EACN;gBACE,IACI,UAAU,CAAC,QAAQ,CAAC,IAAI,CAAC;oBACzB,IAAI,YAAY,KAAK;wBACrB,CAAC,IAAI,CAAC,MAAM,EACd;oBACE,OAAO,KAAK,CAAC,CAAC;iBACjB;qBACI;oBACD,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;iBACzB;aACJ;YACD,OAAO,IAAI,CAAC;QAChB,CAAC,EACD,IAAI,CACP,CAAC;IACN,CAAC;IA3Be,cAAS,YA2BxB,CAAA;AAEL,CAAC,EA1FgB,IAAI,GAAJ,YAAI,KAAJ,YAAI,QA0FpB;AAED;;;;KAIK;AAEL,kBAAe,IAAI,CAAC"} \ No newline at end of file diff --git a/generator/build/Project.d.ts b/generator/build/Project.d.ts new file mode 100644 index 0000000..6f8d8e0 --- /dev/null +++ b/generator/build/Project.d.ts @@ -0,0 +1,13 @@ +/*!* + * + * Copyright (C) Highsoft AS + * + * */ +import * as Parser from '../../parser/build/'; +export declare class Project { + static load(path: string): Promise; + private constructor(); + readonly ast: Parser.Project.JSON; + readonly path: string; +} +export default Project; diff --git a/generator/build/Project.js b/generator/build/Project.js new file mode 100644 index 0000000..4436473 --- /dev/null +++ b/generator/build/Project.js @@ -0,0 +1,58 @@ +"use strict"; +/*!* + * + * Copyright (C) Highsoft AS + * + * */ +var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) { + function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); } + return new (P || (P = Promise))(function (resolve, reject) { + function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } } + function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } } + function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); } + step((generator = generator.apply(thisArg, _arguments || [])).next()); + }); +}; +Object.defineProperty(exports, "__esModule", { value: true }); +exports.Project = void 0; +const FS = require("fs"); +/* * + * + * Class + * + * */ +class Project { + /* * + * + * Constructor + * + * */ + constructor(ast, path) { + this.ast = ast; + this.path = path; + } + /* * + * + * Static Functions + * + * */ + static load(path) { + return __awaiter(this, void 0, void 0, function* () { + const buffer = yield FS.promises.readFile(path); + const ast = JSON.parse(buffer.toString()); + if (ast.files instanceof Array && + typeof ast.name === 'string') { + return new Project(ast, path); + } + throw new Error('Project tree invalid.'); + }); + } +} +exports.Project = Project; +/* * + * + * Default Export + * + * */ +exports.default = Project; +//# sourceMappingURL=Project.js.map \ No newline at end of file diff --git a/generator/build/Project.js.map b/generator/build/Project.js.map new file mode 100644 index 0000000..08ad0a5 --- /dev/null +++ b/generator/build/Project.js.map @@ -0,0 +1 @@ +{"version":3,"file":"Project.js","sourceRoot":"","sources":["../sources/Project.ts"],"names":[],"mappings":";AAAA;;;;KAIK;;;;;;;;;;;;AAEL,yBAAyB;AAGzB;;;;KAIK;AAEL,MAAa,OAAO;IAwBhB;;;;SAIK;IAEL,YACI,GAAwB,EACxB,IAAY;QAEZ,IAAI,CAAC,GAAG,GAAG,GAAG,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IACrB,CAAC;IAlCD;;;;SAIK;IAEE,MAAM,CAAO,IAAI,CACpB,IAAY;;YAEZ,MAAM,MAAM,GAAG,MAAM,EAAE,CAAC,QAAQ,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;YAChD,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,QAAQ,EAAE,CAAC,CAAC;YAE1C,IACI,GAAG,CAAC,KAAK,YAAY,KAAK;gBAC1B,OAAO,GAAG,CAAC,IAAI,KAAK,QAAQ,EAC9B;gBACE,OAAO,IAAI,OAAO,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;aACjC;YAED,MAAM,IAAI,KAAK,CAAC,uBAAuB,CAAC,CAAC;QAC7C,CAAC;KAAA;CA0BJ;AAhDD,0BAgDC;AAED;;;;KAIK;AAEL,kBAAe,OAAO,CAAC"} \ No newline at end of file diff --git a/generator/build/Template.d.ts b/generator/build/Template.d.ts new file mode 100644 index 0000000..352a718 --- /dev/null +++ b/generator/build/Template.d.ts @@ -0,0 +1,17 @@ +/*!* + * + * Copyright (C) Highsoft AS + * + * */ +import JSON from './JSON'; +export declare class Template { + static readonly types: Record; + static load(path: string, relativeTo?: string): Promise