inteligr8/alfresco-ng2-components
1
0
Fork 0
mirror of https://github.com/Alfresco/alfresco-ng2-components.git synced 2025-05-12 17:04:57 +00:00
Code Issues Packages Projects Releases Wiki Activity

[ACS-6659] cleanup unused docs utils (#9274)

Browse Source 
* remove unused scripts

* remove unused scripts

* remove unused scripts

* remove unused libs

* remove unused code

* remove unused code and libs, fix linting issues

* code cleanup

* linting fixes

* linting fixes
This commit is contained in:
Denys Vuika 2024-01-25 10:22:05 -05:00 committed by GitHub
parent 69f24a17ff
commit 5ec8228504
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
25 changed files with 1102 additions and 1949 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
cspell.json
View File

@ -77,7 +77,6 @@
"lastname", "lastname",
"listgrid", "listgrid",
"mapitem", "mapitem",
"markdownlint",
"mimetype", "mimetype",
"mincount", "mincount",
"minlength", "minlength",

41
package-lock.json generated
View File

@ -111,7 +111,6 @@
"eslint-plugin-unicorn": "^49.0.0", "eslint-plugin-unicorn": "^49.0.0",
"github-api": "^3.4.0", "github-api": "^3.4.0",
"graphql": "^16.8.1", "graphql": "^16.8.1",
"graphql-request": "^6.1.0",
"husky": "^7.0.4", "husky": "^7.0.4",
"jasmine-ajax": "4.0.0", "jasmine-ajax": "4.0.0",
"jasmine-core": "4.6.0", "jasmine-core": "4.6.0",
@ -28792,33 +28791,6 @@
"version": "1.5.13", "version": "1.5.13",
"license": "MIT" "license": "MIT"
}, },
"node_modules/cross-fetch": {
"version": "3.1.5",
"dev": true,
"license": "MIT",
"dependencies": {
"node-fetch": "2.6.7"
}
},
"node_modules/cross-fetch/node_modules/node-fetch": {
"version": "2.6.7",
"dev": true,
"license": "MIT",
"dependencies": {
"whatwg-url": "^5.0.0"
},
"engines": {
"node": "4.x || >=6.0.0"
},
"peerDependencies": {
"encoding": "^0.1.0"
},
"peerDependenciesMeta": {
"encoding": {
"optional": true
}
}
},
"node_modules/cross-spawn": { "node_modules/cross-spawn": {
"version": "7.0.3", "version": "7.0.3",
"license": "MIT", "license": "MIT",
@ -33448,19 +33420,6 @@
"node": "^12.22.0 || ^14.16.0 || ^16.0.0 || >=17.0.0" "node": "^12.22.0 || ^14.16.0 || ^16.0.0 || >=17.0.0"
} }
}, },
"node_modules/graphql-request": {
"version": "6.1.0",
"resolved": "https://registry.npmjs.org/graphql-request/-/graphql-request-6.1.0.tgz",
"integrity": "sha512-p+XPfS4q7aIpKVcgmnZKhMNqhltk20hfXtkaIkTfjjmiKMJ5xrt5c743cL03y/K7y1rg3WrIC49xGiEQ4mxdNw==",
"dev": true,
"dependencies": {
"@graphql-typed-document-node/core": "^3.2.0",
"cross-fetch": "^3.1.5"
},
"peerDependencies": {
"graphql": "14 - 16"
}
},
"node_modules/graphql-tag": { "node_modules/graphql-tag": {
"version": "2.12.6", "version": "2.12.6",
"license": "MIT", "license": "MIT",

7
package.json
View File

@ -9,16 +9,10 @@
"ng": "nx", "ng": "nx",
"00": "echo -------------------------------------------- DOC -----------------------------------------------", "00": "echo -------------------------------------------- DOC -----------------------------------------------",
"build-doc-tools": "tsc -p ./tools/doc/tsconfig.json", "build-doc-tools": "tsc -p ./tools/doc/tsconfig.json",
"markdownlint": "markdownlint ./docs",
"docbuild": "(cd ./tools/doc; npm i) && node tools/doc/node_modules/typedoc/bin/typedoc --tsconfig lib/tsconfig.doc.json && node tools/doc/buildYamlSourceInfo.js docs/docs.json && node ./tools/doc/docProcessor.js", "docbuild": "(cd ./tools/doc; npm i) && node tools/doc/node_modules/typedoc/bin/typedoc --tsconfig lib/tsconfig.doc.json && node tools/doc/buildYamlSourceInfo.js docs/docs.json && node ./tools/doc/docProcessor.js",
"review-checker": "node ./tools/doc/reviewChecker.js",
"01": "echo -------------------------------------------- Build Lib -----------------------------------------------", "01": "echo -------------------------------------------- Build Lib -----------------------------------------------",
"affected:libs": "nx affected:libs", "affected:libs": "nx affected:libs",
"coverage": "./lib/config/create-coverage-index.sh && lite-server -c ./lib/config/proxy-coverage.json", "coverage": "./lib/config/create-coverage-index.sh && lite-server -c ./lib/config/proxy-coverage.json",
"print-affected:build": "nx print-affected --target=build --select=tasks.target.project",
"print-affected:test": "nx print-affected --target=test --select=tasks.target.project",
"print-affected:e2e": "nx print-affected --target=e2e --select=tasks.target.project",
"print-affected:lint": "nx print-affected --target=lint --select=tasks.target.project",
"03": "echo -------------------------------------------- Lint -----------------------------------------------", "03": "echo -------------------------------------------- Lint -----------------------------------------------",
"affected:lint": "nx affected:lint", "affected:lint": "nx affected:lint",
"04": "echo -------------------------------------------- Demo Shell -----------------------------------------------", "04": "echo -------------------------------------------- Demo Shell -----------------------------------------------",
@ -161,7 +155,6 @@
"eslint-plugin-unicorn": "^49.0.0", "eslint-plugin-unicorn": "^49.0.0",
"github-api": "^3.4.0", "github-api": "^3.4.0",
"graphql": "^16.8.1", "graphql": "^16.8.1",
"graphql-request": "^6.1.0",
"husky": "^7.0.4", "husky": "^7.0.4",
"jasmine-ajax": "4.0.0", "jasmine-ajax": "4.0.0",
"jasmine-core": "4.6.0", "jasmine-core": "4.6.0",

33
tools/doc/ReviewCheckerGuide.md
View File

@ -1,33 +0,0 @@
# Review checker guide
The review checker tool queries the Github repo to look for recent
commits to the component source files. The dates of these commits
are compared against against a review date stored in the Markdown doc
file for each component. The time and the number of commits since the
last review are then combined into a "score" that gives an indication
of how urgently the doc file needs a review.
## Review date metadata
The review date is kept in the YAML metadata section at the top of each
Markdown file. The key is "Last reviewed" and the date is in the form
YYYY-MM-DD.
## Commit message stoplist
The checker will ignore any commits that match regular expressions stored
in the `commitStoplist.json` file in the `DocProcessor` folder. You could
use this, for example, to filter out JIRA tasks that don't involve any
changes in functionality (and therefore don't need documenting).
## Output format
The script sends comma-separated text to the command line. You can copy/paste
this into a spreadsheet or redirect the output to a text file with a ".csv"
suffix.
To use this tool you need before to set graphAuthToken variable with you github access token:
export graphAuthToken=GITHUB_TOKEN
npm run review-checker

43
tools/doc/buildYamlSourceInfo.js
View File

@ -1,12 +1,12 @@
var fs = require("fs"); const fs = require('fs');
var path = require("path"); const path = require('path');
var ejs = require("ejs"); const ejs = require('ejs');
var templateFolder = path.resolve("tools", "doc", "yamlTemplates"); const templateFolder = path.resolve('tools', 'doc', 'yamlTemplates');
var outputFolder = path.resolve("docs", "sourceinfo"); const outputFolder = path.resolve('docs', 'sourceinfo');
if (process.argv.length < 3) { if (process.argv.length < 3) {
console.log("Error: Source filename required"); console.log('Error: Source filename required');
process.exit(); process.exit();
} }
@ -16,41 +16,36 @@ if (!fs.existsSync(outputFolder)) {
fs.mkdirSync(outputFolder); fs.mkdirSync(outputFolder);
} }
var docData = JSON.parse(fs.readFileSync(path.resolve(process.argv[2]), "utf8")); const docData = JSON.parse(fs.readFileSync(path.resolve(process.argv[2]), 'utf8'));
var tempFilename = path.resolve(templateFolder, "template.ejs"); const tempFilename = path.resolve(templateFolder, 'template.ejs');
var tempSource = fs.readFileSync(tempFilename, "utf8"); const tempSource = fs.readFileSync(tempFilename, 'utf8');
var template = ejs.compile( const template = ejs.compile(tempSource, {
tempSource, filename: tempFilename,
{ cache: true
filename: tempFilename, });
cache: true
}
);
searchItemsRecursively(docData); searchItemsRecursively(docData);
function searchItemsRecursively(item) { function searchItemsRecursively(item) {
if (interestedIn(item.kind)) { if (interestedIn(item.kind)) {
processItem(item); processItem(item);
} else if (item.children) { } else if (item.children) {
item.children.forEach(child => { item.children.forEach((child) => {
searchItemsRecursively(child); searchItemsRecursively(child);
}); });
} }
} }
function interestedIn(itemKind) { function interestedIn(itemKind) {
return (itemKind === 128) || (itemKind === 256) || (itemKind === 4194304); return itemKind === 128 || itemKind === 256 || itemKind === 4194304;
} }
function processItem(item) { function processItem(item) {
var docText = template(item); const docText = template(item);
if( item.name === 'Widget'){ if (item.name === 'Widget') {
console.log('item ' + JSON.stringify(item.name )); console.log('item ' + JSON.stringify(item.name));
} }
fs.writeFileSync(path.resolve(outputFolder, item.name + ".yml"), docText); fs.writeFileSync(path.resolve(outputFolder, item.name + '.yml'), docText);
} }

1
tools/doc/commitStoplist.json
View File

@ -1 +0,0 @@
["ADF-1769"]

163
tools/doc/docProcessor.js
View File

@ -1,25 +1,22 @@
var fs = require("fs"); const fs = require('fs');
var path = require("path"); const path = require('path');
const program = require('commander');
const lodash = require('lodash');
const jsyaml = require('js-yaml');
const remark = require('remark');
const frontMatter = require('remark-frontmatter');
const mdCompact = require('mdast-util-compact');
const minimatch = require('minimatch');
var program = require("commander"); const si = require('./sourceInfoClasses');
var lodash = require("lodash");
var jsyaml = require("js-yaml");
var remark = require("remark");
var frontMatter = require("remark-frontmatter");
var mdCompact = require("mdast-util-compact");
var minimatch = require("minimatch");
var si = require("./sourceInfoClasses");
// "Aggregate" data collected over the whole file set. // "Aggregate" data collected over the whole file set.
var aggData = {}; const aggData = {};
var toolsFolderName = "tools";
var configFileName = "doctool.config.json";
var defaultFolder = path.resolve("docs");
var sourceInfoFolder = path.resolve("docs", "sourceinfo");
const toolsFolderName = 'tools';
const configFileName = 'doctool.config.json';
const defaultFolder = path.resolve('docs');
const sourceInfoFolder = path.resolve('docs', 'sourceinfo');
function filterFiles(filePath) { function filterFiles(filePath) {
let isAllowed = true; let isAllowed = true;
@ -27,31 +24,33 @@ function filterFiles(filePath) {
this.excludedFileList = aggData['config'].exclude; this.excludedFileList = aggData['config'].exclude;
if (this.excludedFileList) { if (this.excludedFileList) {
isAllowed = this.excludedFileList.filter((pattern) => { isAllowed =
return minimatch(filePath, pattern.toString(), { this.excludedFileList.filter((pattern) => {
nocase: true return minimatch(filePath, pattern.toString(), {
}); nocase: true
}).length === 0; });
}).length === 0;
} }
return isAllowed; return isAllowed;
} }
const toolModules = loadToolModules();
let toolList;
function updatePhase(mdCache, aggData) { function updatePhase(mdCache, aggData) {
toolList.forEach((toolName) => {
toolList.forEach(toolName => {
console.log(`Tool: ${toolName}`); console.log(`Tool: ${toolName}`);
toolModules[toolName].processDocs(mdCache, aggData); toolModules[toolName].processDocs(mdCache, aggData);
}); });
var filenames = Object.keys(mdCache); const filenames = Object.keys(mdCache);
for (let i = 0; i < filenames.length; i++) {
for (var i = 0; i < filenames.length; i++) { const pathname = filenames[i];
var pathname = filenames[i]; const tree = mdCache[pathname].mdOutTree;
var tree = mdCache[pathname].mdOutTree; const original = mdCache[pathname].mdInTree;
var original = mdCache[pathname].mdInTree;
if (program.json) { if (program.json) {
let filename = path.basename(pathname); let filename = path.basename(pathname);
@ -67,30 +66,36 @@ function updatePhase(mdCache, aggData) {
console.log(`Modified: ${pathname}`); console.log(`Modified: ${pathname}`);
} }
fs.writeFileSync(filenames[i], remark().use(frontMatter, { fs.writeFileSync(
type: 'yaml', filenames[i],
fence: '---' remark()
}).data("settings", {paddedTable: false, gfm: false}).stringify(tree)); .use(frontMatter, {
type: 'yaml',
fence: '---'
})
.data('settings', { paddedTable: false, gfm: false })
.stringify(tree)
);
} }
} }
} }
function minimiseTree(tree) { function minimiseTree(tree) {
let minPropsTree = JSON.parse(JSON.stringify(tree, (key, value) => key === "position" ? undefined : value)); let minPropsTree = JSON.parse(JSON.stringify(tree, (key, value) => (key === 'position' ? undefined : value)));
mdCompact(minPropsTree); mdCompact(minPropsTree);
return minPropsTree; return minPropsTree;
} }
function loadToolModules() { function loadToolModules() {
var mods = {}; const mods = {};
var toolsFolderPath = path.resolve(__dirname, toolsFolderName); const toolsFolderPath = path.resolve(__dirname, toolsFolderName);
var modFiles = fs.readdirSync(toolsFolderPath); const modFiles = fs.readdirSync(toolsFolderPath);
for (var i = 0; i < modFiles.length; i++) { for (let i = 0; i < modFiles.length; i++) {
var modPath = path.resolve(toolsFolderPath, modFiles[i]) const modPath = path.resolve(toolsFolderPath, modFiles[i]);
if (path.extname(modPath) === ".js") { if (path.extname(modPath) === '.js') {
var toolName = path.basename(modPath, ".js"); const toolName = path.basename(modPath, '.js');
mods[toolName] = require(modPath); mods[toolName] = require(modPath);
} }
} }
@ -98,19 +103,17 @@ function loadToolModules() {
return mods; return mods;
} }
function loadConfig() { function loadConfig() {
var configFilePath = path.resolve(__dirname, configFileName) const configFilePath = path.resolve(__dirname, configFileName);
return JSON.parse(fs.readFileSync(configFilePath)); return JSON.parse(fs.readFileSync(configFilePath));
} }
function getAllDocFilePaths(docFolder, files) { function getAllDocFilePaths(docFolder, files) {
var items = fs.readdirSync(docFolder); const items = fs.readdirSync(docFolder);
for (var i = 0; i < items.length; i++) { for (let i = 0; i < items.length; i++) {
var itemPath = path.resolve(docFolder, items[i]); const itemPath = path.resolve(docFolder, items[i]);
var itemInfo = fs.statSync(itemPath); const itemInfo = fs.statSync(itemPath);
if (itemInfo.isFile()) { if (itemInfo.isFile()) {
files.push(itemPath); files.push(itemPath);
@ -120,16 +123,15 @@ function getAllDocFilePaths(docFolder, files) {
} }
} }
function initMdCache(filenames) { function initMdCache(filenames) {
var mdCache = {}; const mdCache = {};
for (var i = 0; i < filenames.length; i++) { for (let i = 0; i < filenames.length; i++) {
var pathname = filenames[i]; const pathname = filenames[i];
mdCache[pathname] = {}; mdCache[pathname] = {};
var src = fs.readFileSync(pathname); const src = fs.readFileSync(pathname);
var tree = remark().use(frontMatter, ["yaml"]).parse(src); const tree = remark().use(frontMatter, ['yaml']).parse(src);
mdCache[pathname].mdInTree = minimiseTree(tree); mdCache[pathname].mdInTree = minimiseTree(tree);
mdCache[pathname].mdOutTree = minimiseTree(tree); mdCache[pathname].mdOutTree = minimiseTree(tree);
} }
@ -138,13 +140,13 @@ function initMdCache(filenames) {
} }
function initClassInfo(aggData) { function initClassInfo(aggData) {
var yamlFilenames = fs.readdirSync(path.resolve(sourceInfoFolder)); const yamlFilenames = fs.readdirSync(path.resolve(sourceInfoFolder));
aggData.classInfo = {}; aggData.classInfo = {};
yamlFilenames.forEach(yamlFilename => { yamlFilenames.forEach((yamlFilename) => {
var classYamlText = fs.readFileSync(path.resolve(sourceInfoFolder, yamlFilename), "utf8"); const classYamlText = fs.readFileSync(path.resolve(sourceInfoFolder, yamlFilename), 'utf8');
var classYaml = jsyaml.safeLoad(classYamlText); const classYaml = jsyaml.safeLoad(classYamlText);
if (program.verbose) { if (program.verbose) {
console.log(classYaml.items[0].name); console.log(classYaml.items[0].name);
@ -155,20 +157,20 @@ function initClassInfo(aggData) {
} }
program program
.usage("[options] <source>") .usage('[options] <source>')
.option("-p, --profile [profileName]", "Select named config profile", "default") .option('-p, --profile [profileName]', 'Select named config profile', 'default')
.option("-j, --json", "Output JSON data for Markdown syntax tree") .option('-j, --json', 'Output JSON data for Markdown syntax tree')
.option("-v, --verbose", "Log doc files as they are processed") .option('-v, --verbose', 'Log doc files as they are processed')
.option("-t, --timing", "Output time taken for run") .option('-t, --timing', 'Output time taken for run')
.parse(process.argv); .parse(process.argv);
var startTime; let startTime;
if (program.timing) { if (program.timing) {
startTime = process.hrtime(); startTime = process.hrtime();
} }
var sourcePath; let sourcePath;
if (program.args.length === 0) { if (program.args.length === 0) {
sourcePath = defaultFolder; sourcePath = defaultFolder;
@ -176,25 +178,20 @@ if (program.args.length === 0) {
sourcePath = path.resolve(program.args[0]); sourcePath = path.resolve(program.args[0]);
} }
var sourceInfo = fs.statSync(sourcePath); const sourceInfo = fs.statSync(sourcePath);
const config = loadConfig();
var toolModules = loadToolModules();
var config = loadConfig();
aggData['config'] = config; aggData['config'] = config;
var toolList;
if (config.profiles[program.profile]) { if (config.profiles[program.profile]) {
toolList = config.profiles[program.profile]; toolList = config.profiles[program.profile];
var toolListText = toolList.join(", "); var toolListText = toolList.join(', ');
console.log(`Using '${program.profile}' profile: ${toolListText}`); console.log(`Using '${program.profile}' profile: ${toolListText}`);
} else { } else {
console.log(`Aborting: unknown profile '${program.profile}`); console.log(`Aborting: unknown profile '${program.profile}`);
return 0; return 0;
} }
var files = []; let files = [];
if (sourceInfo.isDirectory()) { if (sourceInfo.isDirectory()) {
getAllDocFilePaths(sourcePath, files); getAllDocFilePaths(sourcePath, files);
@ -203,22 +200,18 @@ if (sourceInfo.isDirectory()) {
files = [sourcePath]; files = [sourcePath];
} }
files = files.filter(filename => files = files.filter((filename) => filename !== undefined && path.extname(filename) === '.md' && filename !== 'README.md' && filterFiles(filename));
(filename !== undefined) &&
(path.extname(filename) === ".md") &&
(filename !== "README.md") && filterFiles(filename)
);
var mdCache = initMdCache(files); const mdCache = initMdCache(files);
console.log("Loading source data..."); console.log('Loading source data...');
initClassInfo(aggData); initClassInfo(aggData);
console.log("Updating Markdown files..."); console.log('Updating Markdown files...');
updatePhase(mdCache, aggData); updatePhase(mdCache, aggData);
if (program.timing) { if (program.timing) {
var endTime = process.hrtime(startTime); const endTime = process.hrtime(startTime);
console.log(`Run complete in ${endTime[0]} sec`); console.log(`Run complete in ${endTime[0]} sec`);
} }

42
tools/doc/libsearch.js
View File

@ -1,31 +1,31 @@
var fs = require("fs"); const fs = require('fs');
var path = require("path"); const path = require('path');
module.exports = searchLibraryRecursive; const angFilenameRegex = /([a-zA-Z0-9\-]+)\.((component)|(dialog)|(directive)|(model)|(pipe)|(service)|(widget))\.ts/;
const searchFolderOmitRegex = /(config)|(mock)|(i18n)|(assets)|(styles)/;
var angFilenameRegex = /([a-zA-Z0-9\-]+)\.((component)|(dialog)|(directive)|(model)|(pipe)|(service)|(widget))\.ts/;
var searchFolderOmitRegex = /(config)|(mock)|(i18n)|(assets)|(styles)/;
// Search source folders for .ts files to discover all components, directives, etc. // Search source folders for .ts files to discover all components, directives, etc.
function searchLibraryRecursive(srcData, folderPath) { function searchLibraryRecursive(srcData, folderPath) {
var items = fs.readdirSync(folderPath); const items = fs.readdirSync(folderPath);
for (var i = 0; i < items.length; i++) { for (let i = 0; i < items.length; i++) {
var itemPath = path.resolve(folderPath, items[i]); const itemPath = path.resolve(folderPath, items[i]);
var info = fs.statSync(itemPath); const info = fs.statSync(itemPath);
if (info.isFile() && (items[i].match(angFilenameRegex))) { if (info.isFile() && items[i].match(angFilenameRegex)) {
var nameNoSuffix = path.basename(items[i], '.ts'); const nameNoSuffix = path.basename(items[i], '.ts');
var displayPath = itemPath.replace(/\\/g, '/'); let displayPath = itemPath.replace(/\\/g, '/');
displayPath = displayPath.substr(displayPath.indexOf("lib") + 4); displayPath = displayPath.substring(displayPath.indexOf('lib') + 4);
// Type == "component", "directive", etc. // Type == "component", "directive", etc.
var itemType = nameNoSuffix.split('.')[1]; const itemType = nameNoSuffix.split('.')[1];
srcData[nameNoSuffix] = { "path": displayPath, "type": itemType }; srcData[nameNoSuffix] = { path: displayPath, type: itemType };
} else if (info.isDirectory() && !items[i].match(searchFolderOmitRegex)) { } else if (info.isDirectory() && !items[i].match(searchFolderOmitRegex)) {
searchLibraryRecursive(srcData, itemPath); searchLibraryRecursive(srcData, itemPath);
} }
} }
} }
module.exports = searchLibraryRecursive;

76
tools/doc/mqDefs.ts
View File

@ -17,7 +17,7 @@
import { MDAST } from 'mdast'; import { MDAST } from 'mdast';
import { UNIST } from 'unist'; import { UNIST } from 'unist';
import * as mdToString from 'mdast-util-to-string'; import { toString } from 'mdast-util-to-string';
import * as jsyaml from 'js-yaml'; import * as jsyaml from 'js-yaml';
export const schema = ` export const schema = `
@ -116,7 +116,7 @@ export class Node {
children(): Node[] { children(): Node[] {
if (this.orig['children']) { if (this.orig['children']) {
return this.orig['children'].map(x => new Node(x)); return this.orig['children'].map((x) => new Node(x));
} else { } else {
return null; return null;
} }
@ -124,53 +124,34 @@ export class Node {
} }
export class Parent { export class Parent {
constructor(protected orig: UNIST.Parent) {} constructor(protected orig: UNIST.Parent) {}
plaintext(): string { plaintext(): string {
return mdToString(this.orig); return toString(this.orig);
} }
paragraph(): Paragraph { paragraph(): Paragraph {
return new Paragraph(<MDAST.Paragraph> this.orig.children.find( return new Paragraph(<MDAST.Paragraph>this.orig.children.find((ch: UNIST.Node) => ch.type === 'paragraph'));
(ch: UNIST.Node) => (ch.type === 'paragraph')
));
} }
paragraphs(): Paragraph[] { paragraphs(): Paragraph[] {
return this.orig.children.filter( return this.orig.children.filter((ch: UNIST.Node) => ch.type === 'paragraph').map((ch) => new Paragraph(<MDAST.Paragraph>ch));
(ch: UNIST.Node) =>
(ch.type === 'paragraph')
)
.map(ch => new Paragraph(<MDAST.Paragraph> ch));
} }
link(): Link { link(): Link {
return new Link(<MDAST.Link> this.orig.children.find( return new Link(<MDAST.Link>this.orig.children.find((ch: UNIST.Node) => ch.type === 'link'));
(ch: UNIST.Node) => (ch.type === 'link')
));
} }
links(): Link[] { links(): Link[] {
return this.orig.children.filter( return this.orig.children.filter((ch: UNIST.Node) => ch.type === 'link').map((ch) => new Link(<MDAST.Link>ch));
(ch: UNIST.Node) =>
(ch.type === 'link')
)
.map(ch => new Link(<MDAST.Link> ch));
} }
text(): Text { text(): Text {
return new Text(<MDAST.TextNode> this.orig.children.find( return new Text(<MDAST.TextNode>this.orig.children.find((ch: UNIST.Node) => ch.type === 'text'));
(ch: UNIST.Node) => (ch.type === 'text')
));
} }
texts(): Text[] { texts(): Text[] {
return this.orig.children.filter( return this.orig.children.filter((ch: UNIST.Node) => ch.type === 'text').map((ch) => new Text(<MDAST.TextNode>ch));
(ch: UNIST.Node) =>
(ch.type === 'text')
)
.map(ch => new Text(<MDAST.TextNode> ch));
} }
} }
@ -192,9 +173,7 @@ export class Root extends Parent {
metadata(args): string { metadata(args): string {
if (!this._meta) { if (!this._meta) {
const yamlElement: any = this.orig.children.find( const yamlElement: any = this.orig.children.find((ch: UNIST.Node) => ch.type === 'yaml');
(ch: UNIST.Node) => (ch.type === 'yaml')
);
if (yamlElement) { if (yamlElement) {
this._meta = jsyaml.safeLoad(yamlElement.value); this._meta = jsyaml.safeLoad(yamlElement.value);
@ -213,41 +192,35 @@ export class Root extends Parent {
heading(args): Heading { heading(args): Heading {
const depth = args['depth']; const depth = args['depth'];
return new Heading(<MDAST.Heading> this.orig.children.find( return new Heading(
(ch: UNIST.Node) => <MDAST.Heading>this.orig.children.find((ch: UNIST.Node) => ch.type === 'heading' && (depth === 0 || depth === (<MDAST.Heading>ch).depth))
(ch.type === 'heading') && );
((depth === 0) || (depth === (<MDAST.Heading> ch).depth))
));
} }
headings(args): Heading[] { headings(args): Heading[] {
const depth = args['depth']; const depth = args['depth'];
return this.orig.children.filter( return this.orig.children
(ch: UNIST.Node) => .filter((ch: UNIST.Node) => ch.type === 'heading' && (depth === 0 || depth === (<MDAST.Heading>ch).depth))
(ch.type === 'heading') && .map((ch) => new Heading(<MDAST.Heading>ch));
((depth === 0) || (depth === (<MDAST.Heading> ch).depth)))
.map(ch => new Heading(<MDAST.Heading> ch));
} }
} }
export class Heading extends Parent { export class Heading extends Parent {
depth(): number { depth(): number {
return (<MDAST.Heading> this.orig).depth; return (<MDAST.Heading>this.orig).depth;
} }
} }
export class Paragraph extends Parent { export class Paragraph extends Parent {}
}
export class Link extends Parent { export class Link extends Parent {
title(): string { title(): string {
return (<MDAST.Link> this.orig).title; return (<MDAST.Link>this.orig).title;
} }
url(): string { url(): string {
return (<MDAST.Link> this.orig).url; return (<MDAST.Link>this.orig).url;
} }
} }
@ -269,11 +242,8 @@ export class Docset {
const pathnames = Object.keys(mdCache); const pathnames = Object.keys(mdCache);
pathnames.forEach(pathname => { pathnames.forEach((pathname) => {
if (!pathname.match(/README/) && pathname.match(libNamesRegex)) {
if (!pathname.match(/README/) &&
pathname.match(libNamesRegex)
) {
const doc = new Root(mdCache[pathname].mdInTree); const doc = new Root(mdCache[pathname].mdInTree);
doc.id = pathname.replace(/\\/g, '/'); doc.id = pathname.replace(/\\/g, '/');
this.docs.push(doc); this.docs.push(doc);
@ -285,7 +255,7 @@ export class Docset {
if (args['idFilter'] === '') { if (args['idFilter'] === '') {
return this.docs; return this.docs;
} else { } else {
return this.docs.filter(doc => doc.id.indexOf(args['idFilter'] + '/') !== -1); return this.docs.filter((doc) => doc.id.indexOf(args['idFilter'] + '/') !== -1);
} }
} }

64
tools/doc/ngHelpers.js
View File

@ -1,67 +1,55 @@
module.exports = { module.exports = {
"ngNameToDisplayName": ngNameToDisplayName, ngNameToDisplayName: ngNameToDisplayName,
"ngNameToClassName": ngNameToClassName, ngNameToClassName: ngNameToClassName,
"dekebabifyName": dekebabifyName, dekebabifyName: dekebabifyName,
"kebabifyClassName": kebabifyClassName, kebabifyClassName: kebabifyClassName,
"classTypes": ["component", "dialog", "directive", "model", "pipe", "service", "widget"] classTypes: ['component', 'dialog', 'directive', 'model', 'pipe', 'service', 'widget']
} };
function ngNameToDisplayName(ngName) { function ngNameToDisplayName(ngName) {
var mainSections = ngName.split("."); const mainSections = ngName.split('.');
mainSections[0] = dekebabifyName(mainSections[0]); mainSections[0] = dekebabifyName(mainSections[0]);
return mainSections.join(" "); return mainSections.join(' ');
} }
function initialCap(str) { function initialCap(str) {
return str[0].toUpperCase() + str.substr(1); return str[0].toUpperCase() + str.substr(1);
} }
function ngNameToClassName(rawName, nameExceptions) { function ngNameToClassName(rawName, nameExceptions) {
if (nameExceptions[rawName]) if (nameExceptions[rawName]) return nameExceptions[rawName];
return nameExceptions[rawName];
var name = rawName.replace(/\]|\(|\)/g, ''); const name = rawName.replace(/\]|\(|\)/g, '');
var fileNameSections = name.split('.'); const fileNameSections = name.split('.');
var compNameSections = fileNameSections[0].split('-'); const compNameSections = fileNameSections[0].split('-');
var outCompName = ''; let outCompName = '';
for (var i = 0; i < compNameSections.length; i++) { for (let i = 0; i < compNameSections.length; i++) {
outCompName = outCompName + initialCap(compNameSections[i]); outCompName = outCompName + initialCap(compNameSections[i]);
} }
var itemTypeIndicator = ''; let itemTypeIndicator = '';
if (fileNameSections.length > 1) { if (fileNameSections.length > 1) {
itemTypeIndicator = initialCap(fileNameSections[1]); itemTypeIndicator = initialCap(fileNameSections[1]);
} }
var finalName = outCompName + itemTypeIndicator;
return finalName;
}
function displayNameToNgName(name) { return outCompName + itemTypeIndicator;
var noSpaceName = ngName.replace(/ ([a-zA-Z])/, "$1".toUpperCase());
return noSpaceName.substr(0, 1).toUpperCase() + noSpaceName.substr(1);
} }
function dekebabifyName(name) { function dekebabifyName(name) {
var result = name.replace(/-/g, " "); let result = name.replace(/-/g, ' ');
result = result.substr(0, 1).toUpperCase() + result.substr(1); result = result.substr(0, 1).toUpperCase() + result.substr(1);
return result; return result;
} }
function kebabifyClassName(name) { function kebabifyClassName(name) {
var result = name.replace(/(Component|Directive|Interface|Model|Pipe|Service|Widget)$/, match => { let result = name.replace(/(Component|Directive|Interface|Model|Pipe|Service|Widget)$/, (match) => {
return "." + match.toLowerCase(); return '.' + match.toLowerCase();
}); });
result = result.replace(/([A-Z])/g, "-$1"); result = result.replace(/([A-Z])/g, '-$1');
return result.substr(1).toLowerCase(); return result.substr(1).toLowerCase();
} }

1512
tools/doc/package-lock.json generated
View File

File diff suppressed because it is too large Load Diff

4
tools/doc/package.json
View File

@ -9,15 +9,13 @@
"ejs": "^3.1.6", "ejs": "^3.1.6",
"fast-levenshtein": "^3.0.0", "fast-levenshtein": "^3.0.0",
"graphql": "^15.4.0", "graphql": "^15.4.0",
"graphql-request": "^3.1.0",
"js-yaml": "3.14.1", "js-yaml": "3.14.1",
"markdownlint-cli": "^0.34.0",
"mdast": "3.0.0", "mdast": "3.0.0",
"mdast-util-compact": "1.0.3", "mdast-util-compact": "1.0.3",
"mdast-util-heading-range": "2.1.3", "mdast-util-heading-range": "2.1.3",
"mdast-util-to-string": "^4.0.0",
"mdast-util-toc": "2.1.0", "mdast-util-toc": "2.1.0",
"mdast-zone": "3.0.4", "mdast-zone": "3.0.4",
"moment": "2.29.2",
"remark": "^9.0.0", "remark": "^9.0.0",
"remark-frontmatter": "^1.2.0", "remark-frontmatter": "^1.2.0",
"rxjs": "^6.6.6", "rxjs": "^6.6.6",

23
tools/doc/remarkGraphQl.js
View File

@ -1,23 +0,0 @@
"use strict";
Object.defineProperty(exports, "__esModule", { value: true });
var fs = require("fs");
var path = require("path");
var graphql_1 = require("graphql");
var remark = require("remark");
var frontMatter = require("remark-frontmatter");
var removePosInfo = require("unist-util-remove-position");
var MQ = require("./mqDefs");
var docFilePath = path.resolve('..', '..', 'docs', 'core', 'about.component.md');
var docSrc = fs.readFileSync(docFilePath, 'utf8');
var tree = remark()
.use(frontMatter, ['yaml'])
.parse(docSrc);
tree = removePosInfo(tree);
var schema = (0, graphql_1.buildSchema)(MQ.schema);
var root = {
document: function () { return new MQ.Root(tree); }
};
var query = "\n {\n document {\n metadata(key: \"Status\")\n heading {\n link {\n text {\n value\n }\n }\n }\n paragraph {\n plaintext\n }\n }\n }\n";
(0, graphql_1.graphql)(schema, query, root).then(function (response) {
console.log(JSON.stringify(response));
});

65
tools/doc/remarkGraphQl.ts
View File

@ -1,65 +0,0 @@
/*!
* @license
* Copyright © 2005-2023 Hyland Software, Inc. and its affiliates. All rights reserved.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
import * as fs from 'fs';
import * as path from 'path';
import { graphql, buildSchema } from 'graphql';
import * as remark from 'remark';
import * as frontMatter from 'remark-frontmatter';
import { MDAST } from 'mdast';
import * as removePosInfo from 'unist-util-remove-position';
import * as MQ from './mqDefs';
const docFilePath = path.resolve('..', '..', 'docs', 'core', 'about.component.md');
const docSrc = fs.readFileSync(docFilePath, 'utf8');
let tree: MDAST.Root = remark()
.use(frontMatter, ['yaml'])
.parse(docSrc);
tree = removePosInfo(tree);
const schema = buildSchema(MQ.schema);
const root = {
document: () => new MQ.Root(tree)
};
const query = `
{
document {
metadata(key: "Status")
heading {
link {
text {
value
}
}
}
paragraph {
plaintext
}
}
}
`;
graphql(schema, query, root).then((response) => {
console.log(JSON.stringify(response));
});

109
tools/doc/reviewChecker.js
View File

@ -1,109 +0,0 @@
"use strict";
Object.defineProperty(exports, "__esModule", { value: true });
var path = require("path");
var fs = require("fs");
var process = require("process");
var graphql_request_1 = require("graphql-request");
var remark = require("remark");
var frontMatter = require("remark-frontmatter");
var yaml = require("js-yaml");
var moment = require("moment");
var rxjs_1 = require("rxjs");
var libsearch = require("./libsearch");
var stoplist_1 = require("./stoplist");
var adf20StartDate = '2017-11-20';
var commitWeight = 0.1;
var scoreTimeBase = 60;
var libFolder = 'lib';
var stoplistFilePath = path.resolve('tools', 'doc', 'commitStoplist.json');
var angFilePattern = /(component)|(directive)|(model)|(pipe)|(service)|(widget)/;
var srcData = {};
var stoplist = new stoplist_1.Stoplist(stoplistFilePath);
var docsFolderPath = path.resolve('docs');
var libFolders = ['core', 'content-services', 'extensions', 'insights', 'process-services', 'process-services-cloud'];
libsearch(srcData, path.resolve(libFolder));
var authToken = process.env.graphAuthToken;
var client = new graphql_request_1.GraphQLClient('https://api.github.com/graphql', {
headers: {
Authorization: 'Bearer ' + authToken
}
});
var query = "query commitHistory($path: String) {\n repository(name: \"alfresco-ng2-components\", owner: \"alfresco\") {\n ref(qualifiedName: \"development\") {\n target {\n ... on Commit {\n history(first: 15, path: $path) {\n nodes {\n pushedDate\n message\n }\n }\n }\n }\n }\n }\n}";
var docFiles = getDocFilePaths(docsFolderPath);
var docNames = (0, rxjs_1.of)(docFiles);
console.log("'Name','Review date','Commits since review','Score'");
docNames.subscribe(function (docs) {
docs.forEach(function (x) {
var key = path.basename(x, '.md');
if (!srcData[key]) {
return;
}
var vars = {
'path': 'lib/' + srcData[key].path
};
client.request(query, vars).then(function (data) {
var nodes = data['repository'].ref.target.history.nodes;
var lastReviewDate = getDocReviewDate(x); // (key + ".md");
var numUsefulCommits = extractCommitInfo(nodes, lastReviewDate, stoplist);
if (numUsefulCommits > 0) {
var dateString = lastReviewDate.format('YYYY-MM-DD');
var score = priorityScore(lastReviewDate, numUsefulCommits).toPrecision(3);
console.log("'".concat(key, "','").concat(dateString, "','").concat(numUsefulCommits, "','").concat(score, "'"));
}
});
});
});
function priorityScore(reviewDate, numCommits) {
var daysSinceReview = moment().diff(reviewDate, 'days');
var commitScore = 2 + numCommits * commitWeight;
return Math.pow(commitScore, daysSinceReview / scoreTimeBase);
}
function getDocReviewDate(docFileName) {
var mdFilePath = path.resolve(docsFolderPath, docFileName);
var mdText = fs.readFileSync(mdFilePath);
var tree = remark().use(frontMatter, ['yaml']).parse(mdText);
var lastReviewDate = moment(adf20StartDate);
if (tree.children[0].type === 'yaml') {
var metadata = yaml.load(tree.children[0].value);
if (metadata['Last reviewed']) {
lastReviewDate = moment(metadata['Last reviewed']);
}
}
return lastReviewDate;
}
function extractCommitInfo(commitNodes, cutOffDate, stoplist) {
var numUsefulCommits = 0;
commitNodes.forEach(function (element) {
if (!stoplist.isRejected(element.message)) {
// const abbr = element.message.substr(0, 15);
var commitDate = moment(element.pushedDate);
if (commitDate.isAfter(cutOffDate)) {
numUsefulCommits++;
}
}
});
return numUsefulCommits;
}
function getDocFilePaths(folderPath) {
var result = [];
libFolders.forEach(function (element) {
var libPath = path.resolve(folderPath, element);
addItemsRecursively(libPath, result);
});
return result;
function addItemsRecursively(elementPath, resultList) {
var items = fs.readdirSync(elementPath);
items.forEach(function (item) {
var fullItemPath = path.resolve(elementPath, item);
var itemInfo = fs.statSync(fullItemPath);
if (itemInfo.isDirectory()) {
addItemsRecursively(fullItemPath, resultList);
}
else if ((path.extname(fullItemPath) === '.md') &&
(item !== 'README.md') &&
(item.match(angFilePattern))) {
resultList.push(fullItemPath);
}
});
}
}

182
tools/doc/reviewChecker.ts
View File

@ -1,182 +0,0 @@
/*!
* @license
* Copyright © 2005-2023 Hyland Software, Inc. and its affiliates. All rights reserved.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
import * as path from 'path';
import * as fs from 'fs';
import * as process from 'process';
import { GraphQLClient } from 'graphql-request';
import * as remark from 'remark';
import * as frontMatter from 'remark-frontmatter';
import * as yaml from 'js-yaml';
import * as moment from 'moment';
import { of } from 'rxjs';
import * as libsearch from './libsearch';
import { Stoplist } from './stoplist';
const adf20StartDate = '2017-11-20';
const commitWeight = 0.1;
const scoreTimeBase = 60;
const libFolder = 'lib';
const stoplistFilePath = path.resolve('tools', 'doc', 'commitStoplist.json');
const angFilePattern = /(component)|(directive)|(model)|(pipe)|(service)|(widget)/;
const srcData = {};
const stoplist = new Stoplist(stoplistFilePath);
const docsFolderPath = path.resolve('docs');
const libFolders = ['core', 'content-services', 'extensions', 'insights', 'process-services', 'process-services-cloud'];
libsearch(srcData, path.resolve(libFolder));
const authToken = process.env.graphAuthToken;
const client = new GraphQLClient('https://api.github.com/graphql', {
headers: {
Authorization: 'Bearer ' + authToken
}
});
const query = `query commitHistory($path: String) {
repository(name: "alfresco-ng2-components", owner: "alfresco") {
ref(qualifiedName: "development") {
target {
... on Commit {
history(first: 15, path: $path) {
nodes {
pushedDate
message
}
}
}
}
}
}
}`;
const docFiles = getDocFilePaths(docsFolderPath);
const docNames = of(docFiles);
console.log('\'Name\',\'Review date\',\'Commits since review\',\'Score\'');
docNames.subscribe(docs => {
docs.forEach(x => {
const key = path.basename(x, '.md');
if (!srcData[key]) {
return;
}
const vars = {
path: 'lib/' + srcData[key].path
};
client.request(query, vars).then(data => {
const nodes = data['repository'].ref.target.history.nodes;
const lastReviewDate = getDocReviewDate(x); // (key + ".md");
const numUsefulCommits = extractCommitInfo(nodes, lastReviewDate, stoplist);
if (numUsefulCommits > 0) {
const dateString = lastReviewDate.format('YYYY-MM-DD');
const score = priorityScore(lastReviewDate, numUsefulCommits).toPrecision(3);
console.log(`'${key}','${dateString}','${numUsefulCommits}','${score}'`);
}
});
});
});
function priorityScore(reviewDate, numCommits) {
const daysSinceReview = moment().diff(reviewDate, 'days');
const commitScore = 2 + numCommits * commitWeight;
return Math.pow(commitScore, daysSinceReview / scoreTimeBase);
}
function getDocReviewDate(docFileName) {
const mdFilePath = path.resolve(docsFolderPath, docFileName);
const mdText = fs.readFileSync(mdFilePath);
const tree = remark().use(frontMatter, ['yaml']).parse(mdText);
let lastReviewDate = moment(adf20StartDate);
if (tree.children[0].type === 'yaml') {
const metadata = yaml.load(tree.children[0].value);
if (metadata['Last reviewed']) {
lastReviewDate = moment(metadata['Last reviewed']);
}
}
return lastReviewDate;
}
function extractCommitInfo(commitNodes, cutOffDate, stoplist) {
let numUsefulCommits = 0;
commitNodes.forEach(element => {
if (!stoplist.isRejected(element.message)) {
// const abbr = element.message.substr(0, 15);
const commitDate = moment(element.pushedDate);
if (commitDate.isAfter(cutOffDate)) {
numUsefulCommits++;
}
}
});
return numUsefulCommits;
}
function getDocFilePaths(folderPath) {
const result = [];
libFolders.forEach(element => {
const libPath = path.resolve(folderPath, element);
addItemsRecursively(libPath, result);
});
return result;
function addItemsRecursively(elementPath: string, resultList: string[]) {
const items = fs.readdirSync(elementPath);
items.forEach(item => {
const fullItemPath = path.resolve(elementPath, item);
const itemInfo = fs.statSync(fullItemPath);
if (itemInfo.isDirectory()) {
addItemsRecursively(fullItemPath, resultList);
} else if (
(path.extname(fullItemPath) === '.md') &&
(item !== 'README.md') &&
(item.match(angFilePattern))
) {
resultList.push(fullItemPath);
}
});
}
}

30
tools/doc/stoplist.js
View File

@ -1,30 +0,0 @@
"use strict";
Object.defineProperty(exports, "__esModule", { value: true });
exports.Stoplist = void 0;
var fs = require("fs");
/* "Stoplist" of regular expressions to match against strings. */
var Stoplist = /** @class */ (function () {
function Stoplist(slFilePath) {
var listExpressions = JSON.parse(fs.readFileSync(slFilePath, 'utf8'));
this.regexes = [];
if (listExpressions) {
for (var i = 0; i < listExpressions.length; i++) {
this.regexes.push(new RegExp(listExpressions[i]));
}
}
else {
this.regexes = [];
}
}
// Check if an item is covered by the stoplist and reject it if so.
Stoplist.prototype.isRejected = function (itemName) {
for (var i = 0; i < this.regexes.length; i++) {
if (this.regexes[i].test(itemName)) {
return true;
}
}
return false;
};
return Stoplist;
}());
exports.Stoplist = Stoplist;

48
tools/doc/stoplist.ts
View File

@ -1,48 +0,0 @@
/*!
* @license
* Copyright © 2005-2023 Hyland Software, Inc. and its affiliates. All rights reserved.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
import * as fs from 'fs';
/* "Stoplist" of regular expressions to match against strings. */
export class Stoplist {
regexes: RegExp[];
constructor(slFilePath: string) {
const listExpressions = JSON.parse(fs.readFileSync(slFilePath, 'utf8'));
this.regexes = [];
if (listExpressions) {
for (let i = 0; i < listExpressions.length; i++) {
this.regexes.push(new RegExp(listExpressions[i]));
}
} else {
this.regexes = [];
}
}
// Check if an item is covered by the stoplist and reject it if so.
isRejected(itemName: string) {
for (let i = 0; i < this.regexes.length; i++) {
if (this.regexes[i].test(itemName)) {
return true;
}
}
return false;
}
}

77
tools/doc/tools/seealso.js
View File

@ -1,23 +1,19 @@
var path = require("path"); const path = require('path');
const unist = require('../unistHelpers');
var unist = require("../unistHelpers"); const seeAlsoHeading = 'See Also';
var seeAlsoHeading = "See Also";
module.exports = { module.exports = {
"initPhase": initPhase, initPhase: initPhase,
"readPhase": readPhase, readPhase: readPhase,
"aggPhase": aggPhase, aggPhase: aggPhase,
"updatePhase": updatePhase updatePhase: updatePhase
} };
function initPhase(aggData) { function initPhase(aggData) {
aggData.saGraph = {}; aggData.saGraph = {};
aggData.saUpdateGraph = {}; aggData.saUpdateGraph = {};
} }
function readPhase(tree, pathname, aggData) { function readPhase(tree, pathname, aggData) {
var saHeadingOffset = findSeeAlsoSection(tree); var saHeadingOffset = findSeeAlsoSection(tree);
@ -27,13 +23,9 @@ function readPhase(tree, pathname, aggData) {
// Skip over non-list parts. // Skip over non-list parts.
var s; var s;
for ( for (s = saHeadingOffset; s < tree.children.length && !unist.isListUnordered(tree.children[s]); s++);
s = saHeadingOffset;
(s < tree.children.length) && !unist.isListUnordered(tree.children[s]);
s++
);
if ((s < tree.children.length) && unist.isListUnordered(tree.children[s])) { if (s < tree.children.length && unist.isListUnordered(tree.children[s])) {
var list = tree.children[s]; var list = tree.children[s];
for (var i = 0; i < list.children.length; i++) { for (var i = 0; i < list.children.length; i++) {
@ -46,17 +38,15 @@ function readPhase(tree, pathname, aggData) {
} }
} }
aggData.saGraph[path.basename(pathname, ".md")] = saNode; aggData.saGraph[path.basename(pathname, '.md')] = saNode;
} }
function aggPhase(aggData) { function aggPhase(aggData) {
aggData.saUpdateGraph = tidyGraph(aggData.saGraph); aggData.saUpdateGraph = tidyGraph(aggData.saGraph);
} }
function updatePhase(tree, pathname, aggData) { function updatePhase(tree, pathname, aggData) {
var currNodeName = path.basename(pathname, ".md"); var currNodeName = path.basename(pathname, '.md');
var currNodeArcs = aggData.saUpdateGraph[currNodeName]; var currNodeArcs = aggData.saUpdateGraph[currNodeName];
if (currNodeArcs.length > 0) { if (currNodeArcs.length > 0) {
@ -64,7 +54,7 @@ function updatePhase(tree, pathname, aggData) {
for (var i = 0; i < currNodeArcs.length; i++) { for (var i = 0; i < currNodeArcs.length; i++) {
var linkText = graphKeyToLinkName(currNodeArcs[i]); var linkText = graphKeyToLinkName(currNodeArcs[i]);
var linkTarget = currNodeArcs[i] + ".md"; var linkTarget = currNodeArcs[i] + '.md';
var link = unist.makeLink(unist.makeText(linkText), linkTarget); var link = unist.makeLink(unist.makeText(linkText), linkTarget);
saListItems.push(unist.makeListItem(link)); saListItems.push(unist.makeListItem(link));
} }
@ -75,11 +65,7 @@ function updatePhase(tree, pathname, aggData) {
// Skip over non-list parts. // Skip over non-list parts.
var s; var s;
for ( for (s = saHeadingOffset; s < tree.children.length && !unist.isListUnordered(tree.children[s]); s++);
s = saHeadingOffset;
(s < tree.children.length) && !unist.isListUnordered(tree.children[s]);
s++
);
// Push all elements of the items array as if they were separate elements. // Push all elements of the items array as if they were separate elements.
Array.prototype.push.apply(tree.children[s].children, saListItems); Array.prototype.push.apply(tree.children[s].children, saListItems);
@ -93,39 +79,30 @@ function updatePhase(tree, pathname, aggData) {
return true; return true;
} }
function graphKeyToLinkName(key) { function graphKeyToLinkName(key) {
var mainSections = key.split("."); var mainSections = key.split('.');
mainSections[0] = tidyName(mainSections[0]); mainSections[0] = tidyName(mainSections[0]);
return mainSections.join(" "); return mainSections.join(' ');
} }
// Convert an Angular-style name (eg, "card-view") into one with correct spaces and uppercase (eg, "Card view"). // Convert an Angular-style name (eg, "card-view") into one with correct spaces and uppercase (eg, "Card view").
function tidyName(name) { function tidyName(name) {
var result = name.replace(/-/g, " "); var result = name.replace(/-/g, ' ');
result = result.substr(0, 1).toUpperCase() + result.substr(1); result = result.substr(0, 1).toUpperCase() + result.substr(1);
return result; return result;
} }
function makeEmptySAList() {
var result = [];
}
// Makes link symmetrical between items (ie, if A links to B but not the other way // Makes link symmetrical between items (ie, if A links to B but not the other way
// around then it adds the missing link). // around then it adds the missing link).
function tidyGraph(graph) { function tidyGraph(graph) {
var nodeNames = Object.keys(graph); var nodeNames = Object.keys(graph);
var result = {}; var result = {};
for (var n = 0; n < nodeNames.length; n++) { for (let n = 0; n < nodeNames.length; n++) {
result[nodeNames[n]] = []; result[nodeNames[n]] = [];
} }
for (var n = 0; n < nodeNames.length; n++) { for (let n = 0; n < nodeNames.length; n++) {
var currNodeName = nodeNames[n]; var currNodeName = nodeNames[n];
var currNodeArcs = graph[currNodeName]; var currNodeArcs = graph[currNodeName];
@ -146,29 +123,21 @@ function tidyGraph(graph) {
return result; return result;
} }
function findSeeAlsoSection(tree) { function findSeeAlsoSection(tree) {
var i; var i;
for (i = 0; i < tree.children.length; i++) { for (i = 0; i < tree.children.length; i++) {
var child = tree.children[i]; var child = tree.children[i];
if (unist.isHeading(child) && (child.children[0].value.toLowerCase() === seeAlsoHeading.toLowerCase())) if (unist.isHeading(child) && child.children[0].value.toLowerCase() === seeAlsoHeading.toLowerCase()) return i;
return i;
} }
return -1; return -1;
} }
function getItemLinkInfo(listItem) { function getItemLinkInfo(listItem) {
var linkTarget = listItem.children[0].children[0].url; var linkTarget = listItem.children[0].children[0].url;
if (linkTarget.startsWith("http:") || if (linkTarget.startsWith('http:') || linkTarget.startsWith('#') || !linkTarget.endsWith('.md')) return null;
linkTarget.startsWith("#") || else return path.basename(linkTarget, '.md');
!linkTarget.endsWith(".md"))
return null;
else
return path.basename(linkTarget, ".md");
} }

133
tools/doc/tools/toc.js
View File

@ -1,51 +1,43 @@
var path = require("path"); const path = require('path');
var fs = require("fs"); const fs = require('fs');
const remark = require('remark');
const replaceSection = require('mdast-util-heading-range');
const { toString } = require('mdast-util-to-string');
const ejs = require('ejs');
const unist = require('../unistHelpers');
const mdNav = require('../mdNav');
var remark = require("remark"); const contentsHeading = 'Contents';
//var tocGenerator = require("mdast-util-toc");
var replaceSection = require("mdast-util-heading-range");
var tostring = require("mdast-util-to-string");
var ejs = require("ejs");
var unist = require("../unistHelpers");
var mdNav = require("../mdNav");
const contentsHeading = "Contents";
const minHeadingsForToc = 8; const minHeadingsForToc = 8;
const maxTocHeadingDepth = 3; const maxTocHeadingDepth = 3;
var templateFolder = path.resolve("tools", "doc", "templates"); const templateFolder = path.resolve('tools', 'doc', 'templates');
module.exports = { module.exports = {
"processDocs": processDocs processDocs: processDocs
} };
function processDocs(mdCache, aggData, errorMessages) { function processDocs(mdCache, aggData, errorMessages) {
var pathnames = Object.keys(mdCache); const pathNames = Object.keys(mdCache);
pathnames.forEach(pathname => { pathNames.forEach((pathname) => {
updateFile(mdCache[pathname].mdOutTree, pathname, aggData, errorMessages); updateFile(mdCache[pathname].mdOutTree, pathname, aggData, errorMessages);
}); });
} }
// Find an existing Contents section or add a new empty one if needed. // Find an existing Contents section or add a new empty one if needed.
// Returns true if section is present/needed, false if not needed. // Returns true if section is present/needed, false if not needed.
function establishContentsSection(mdTree) { function establishContentsSection(mdTree) {
var firstL2HeadingPos = -1; let firstL2HeadingPos = -1;
var numTocHeadings = 0; let numTocHeadings = 0;
var foundContentsHeading = false; let foundContentsHeading = false;
for (let i = 0; i < mdTree.children.length; i++) {
const child = mdTree.children[i];
for (var i = 0; i < mdTree.children.length; i++) {
var child = mdTree.children[i];
// Look through all headings. // Look through all headings.
if (child.type === "heading") { if (child.type === 'heading') {
if (child.depth > 1 && child.depth <= maxTocHeadingDepth) {
if ((child.depth > 1) && (child.depth <= maxTocHeadingDepth)) {
numTocHeadings++; numTocHeadings++;
} }
@ -57,7 +49,7 @@ function establishContentsSection(mdTree) {
// If it is also a Contents heading then we're done. We don't include the // If it is also a Contents heading then we're done. We don't include the
// Contents heading itself within the ToC, so decrement the count for that. // Contents heading itself within the ToC, so decrement the count for that.
if ((child.children[0].value === contentsHeading) && !foundContentsHeading) { if (child.children[0].value === contentsHeading && !foundContentsHeading) {
foundContentsHeading = true; foundContentsHeading = true;
numTocHeadings--; numTocHeadings--;
} }
@ -69,42 +61,38 @@ function establishContentsSection(mdTree) {
// If there are enough headings for a ToC to be necessary then // If there are enough headings for a ToC to be necessary then
// add one in the right place. // add one in the right place.
if (!foundContentsHeading) { if (!foundContentsHeading) {
var newContsHeading = unist.makeHeading(unist.makeText(contentsHeading), 2); const newHeading = unist.makeHeading(unist.makeText(contentsHeading), 2);
// If we found another L2 heading then add the Contents in just before it. // If we found another L2 heading then add the Contents in just before it.
if (firstL2HeadingPos != -1) { if (firstL2HeadingPos !== -1) {
mdTree.children.splice(firstL2HeadingPos, 0, newContsHeading); mdTree.children.splice(firstL2HeadingPos, 0, newHeading);
} else { } else {
// Otherwise, the unlikely situation where a ToC is required but there // Otherwise, the unlikely situation where a ToC is required but there
// are no L2 headings! Add it as the second element in the document. // are no L2 headings! Add it as the second element in the document.
mdTree.children.splice(1, 0, newContsHeading); mdTree.children.splice(1, 0, newHeading);
} }
} }
return numTocHeadings; return numTocHeadings;
} }
function updateFile(tree, pathname, _aggData, _errorMessages) { function updateFile(tree, pathname, _aggData, _errorMessages) {
if (path.basename(pathname, ".md").match(/README|versionIndex/)) { if (path.basename(pathname, '.md').match(/README|versionIndex/)) {
return false; return false;
} }
// If we need a contents section then add one or update the existing one. // If we need a contents section then add one or update the existing one.
var numTocHeadings = establishContentsSection(tree); const numTocHeadings = establishContentsSection(tree);
if (numTocHeadings >= minHeadingsForToc) { if (numTocHeadings >= minHeadingsForToc) {
var newToc = makeToc(tree); //tocGenerator(tree, {heading: contentsHeading, maxDepth: 3}); const newToc = makeToc(tree);
replaceSection(tree, contentsHeading, function(before, oldSection, after) { replaceSection(tree, contentsHeading, function (before, oldSection, after) {
return [before, newToc, after]; return [before, newToc, after];
}); });
} else { } else {
// Otherwise, we don't need one, so remove any existing one. // Otherwise, we don't need one, so remove any existing one.
replaceSection(tree, contentsHeading, function(before, oldSection, after) { replaceSection(tree, contentsHeading, function (before, oldSection, after) {
return [after]; return [after];
}); });
} }
@ -112,44 +100,39 @@ function updateFile(tree, pathname, _aggData, _errorMessages) {
return true; return true;
} }
function makeToc(tree) { function makeToc(tree) {
var nav = new mdNav.MDNav(tree); const nav = new mdNav.MDNav(tree);
const headings = nav.headings((h) => h.depth > 1 && h.depth <= maxTocHeadingDepth);
const context = { headings: [] };
var headings = nav.headings(h => headings.forEach((heading) => {
(h.depth > 1) && let linkTitle = '';
(h.depth <= maxTocHeadingDepth) //&&
//!((h.children[0].type === "text") && (h.children[0].value === "Contents"))
);
var context = {headings: []}; if (!(heading.item.children.length > 0 && heading.item.children[0].type === 'text' && heading.item.children[0].value === 'Contents')) {
linkTitle = toString(heading.item).trim();
headings.forEach(heading => {
var linkTitle = "";
if (!((heading.item.children.length > 0) && (heading.item.children[0].type === "text") && (heading.item.children[0].value === "Contents"))) {
linkTitle = tostring(heading.item).trim();
} }
if (linkTitle !== "") { if (linkTitle !== '') {
context.headings.push({ context.headings.push({
"level": heading.item.depth - 2, level: heading.item.depth - 2,
"title": linkTitle, title: linkTitle,
//"anchor": "#" + linkTitle.toLowerCase().replace(/ /g, "-").replace(/[:;@\.,'"`$\(\)\/]/g ,"") anchor:
"anchor": "#" + linkTitle.toLowerCase() '#' +
.replace(/[^a-z0-9\s\-_]/g, '') linkTitle
.replace(/\s/g ,"-") .toLowerCase()
.replace(/\-+$/, '') .replace(/[^a-z0-9\s\-_]/g, '')
}) .replace(/\s/g, '-')
}; .replace(/-+$/, '')
});
}
}); });
var templateName = path.resolve(templateFolder, "toc.ejs"); const templateName = path.resolve(templateFolder, 'toc.ejs');
var templateSource = fs.readFileSync(templateName, "utf8"); const templateSource = fs.readFileSync(templateName, 'utf8');
var template = ejs.compile(templateSource); const template = ejs.compile(templateSource);
var mdText = template(context); const mdText = template(context);
var newMD = remark().parse(mdText); const newMD = remark().parse(mdText);
return newMD.children[0]; return newMD.children[0];
} }

97
tools/doc/tools/tsInfo.ts
View File

@ -31,10 +31,10 @@ let nameExceptions;
export function processDocs(mdCache, aggData) { export function processDocs(mdCache, aggData) {
nameExceptions = aggData.config.typeNameExceptions; nameExceptions = aggData.config.typeNameExceptions;
const pathnames = Object.keys(mdCache); const pathNames = Object.keys(mdCache);
let internalErrors; let internalErrors;
pathnames.forEach(pathname => { pathNames.forEach((pathname) => {
internalErrors = []; internalErrors = [];
updateFile(mdCache[pathname].mdOutTree, pathname, aggData, internalErrors); updateFile(mdCache[pathname].mdOutTree, pathname, aggData, internalErrors);
@ -47,7 +47,7 @@ export function processDocs(mdCache, aggData) {
function showErrors(filename, errorMessages) { function showErrors(filename, errorMessages) {
console.log(filename); console.log(filename);
errorMessages.forEach(message => { errorMessages.forEach((message) => {
console.log(' ' + message); console.log(' ' + message);
}); });
@ -55,7 +55,6 @@ function showErrors(filename, errorMessages) {
} }
function updateFile(tree, pathname, aggData, errorMessages) { function updateFile(tree, pathname, aggData, errorMessages) {
const className = ngNameToClassName(path.basename(pathname, '.md'), nameExceptions); const className = ngNameToClassName(path.basename(pathname, '.md'), nameExceptions);
const classTypeMatch = className.match(/component|directive|service/i); const classTypeMatch = className.match(/component|directive|service/i);
const compData = aggData.classInfo[className]; const compData = aggData.classInfo[className];
@ -67,8 +66,6 @@ function updateFile(tree, pathname, aggData, errorMessages) {
const inputMD = getPropDocsFromMD(tree, 'Properties', 3); const inputMD = getPropDocsFromMD(tree, 'Properties', 3);
const outputMD = getPropDocsFromMD(tree, 'Events', 2); const outputMD = getPropDocsFromMD(tree, 'Events', 2);
updatePropDocsFromMD(compData, inputMD, outputMD, errorMessages); updatePropDocsFromMD(compData, inputMD, outputMD, errorMessages);
if (classType === 'service') { if (classType === 'service') {
@ -81,7 +78,7 @@ function updateFile(tree, pathname, aggData, errorMessages) {
const template = ejs.compile(templateSource); const template = ejs.compile(templateSource);
let mdText = template(compData); let mdText = template(compData);
mdText = mdText.replace(/^ +\|/mg, '|'); mdText = mdText.replace(/^ +\|/gm, '|');
const newSection = remark().parse(mdText.trim()).children; const newSection = remark().parse(mdText.trim()).children;
@ -91,7 +88,7 @@ function updateFile(tree, pathname, aggData, errorMessages) {
return newSection; return newSection;
}); });
compData.errors.forEach(err => { compData.errors.forEach((err) => {
errorMessages.push(err); errorMessages.push(err);
}); });
} }
@ -104,37 +101,31 @@ function getPropDocsFromMD(tree, sectionHeading, docsColumn) {
const nav = new MDNav(tree); const nav = new MDNav(tree);
const classMemHeading = nav const classMemHeading = nav.heading((h) => {
.heading(h => { return h.children[0].type === 'text' && h.children[0].value === 'Class members';
return (h.children[0].type === 'text') && (h.children[0].value === 'Class members'); });
});
const propsTable = classMemHeading const propsTable = classMemHeading
.heading(h => { .heading((h) => {
return (h.children[0].type === 'text') && (h.children[0].value === sectionHeading); return h.children[0].type === 'text' && h.children[0].value === sectionHeading;
}).table(); })
.table();
let propTableRow = propsTable.childNav let propTableRow = propsTable.childNav.tableRow(() => true, 1).childNav;
.tableRow(() => true, 1).childNav;
let i = 1; let i = 1;
while (!propTableRow.empty) { while (!propTableRow.empty) {
const propName = propTableRow const propName = propTableRow.tableCell().childNav.text().item.value;
.tableCell().childNav
.text().item.value;
const propDocText = propTableRow const propDocText = propTableRow.tableCell(() => true, docsColumn).childNav.text().item;
.tableCell(() => true, docsColumn).childNav
.text().item;
if (propDocText) { if (propDocText) {
result[propName] = propDocText.value; result[propName] = propDocText.value;
} }
i++; i++;
propTableRow = propsTable.childNav propTableRow = propsTable.childNav.tableRow(() => true, i).childNav;
.tableRow(() => true, i).childNav;
} }
return result; return result;
@ -145,25 +136,22 @@ function getMethodDocsFromMD(tree) {
const nav = new MDNav(tree); const nav = new MDNav(tree);
const classMemHeading = nav const classMemHeading = nav.heading((h) => {
.heading(h => { return h.children[0].type === 'text' && h.children[0].value === 'Class members';
return (h.children[0].type === 'text') && (h.children[0].value === 'Class members'); });
});
const methListItems = classMemHeading const methListItems = classMemHeading
.heading(h => { .heading((h) => {
return (h.children[0].type === 'text') && (h.children[0].value === 'Methods'); return h.children[0].type === 'text' && h.children[0].value === 'Methods';
}).list().childNav; })
.list().childNav;
let methItem = methListItems let methItem = methListItems.listItem();
.listItem();
let i = 0; let i = 0;
while (!methItem.empty) { while (!methItem.empty) {
const methNameSection = methItem.childNav const methNameSection = methItem.childNav.paragraph().childNav.strong().childNav;
.paragraph().childNav
.strong().childNav;
let methName = ''; let methName = '';
@ -171,23 +159,19 @@ function getMethodDocsFromMD(tree) {
if (!methNameSection.empty) { if (!methNameSection.empty) {
methName = methNameSection.text().item.value; methName = methNameSection.text().item.value;
const methDoc = methItem.childNav const methDoc = methItem.childNav.paragraph().childNav.html().text().value;
.paragraph().childNav
.html()
.text().value;
const params = getMDMethodParams(methItem); const params = getMDMethodParams(methItem);
result[methName] = { result[methName] = {
'docText': methDoc.replace(/^\n/, ''), docText: methDoc.replace(/^\n/, ''),
'params': params params: params
}; };
} }
i++; i++;
methItem = methListItems methItem = methListItems.listItem((l) => true, i);
.listItem(l => true, i);
} }
return result; return result;
@ -198,31 +182,24 @@ function getMDMethodParams(methItem: MDNav) {
const paramList = methItem.childNav.list().childNav; const paramList = methItem.childNav.list().childNav;
const paramListItems = paramList const paramListItems = paramList.listItems();
.listItems();
paramListItems.forEach(paramListItem => { paramListItems.forEach((paramListItem) => {
const paramNameNode = paramListItem.childNav const paramNameNode = paramListItem.childNav.paragraph().childNav.emph().childNav;
.paragraph().childNav
.emph().childNav;
let paramName; let paramName;
if (!paramNameNode.empty) { if (!paramNameNode.empty) {
paramName = paramNameNode.text().item.value.replace(/:/, ''); paramName = paramNameNode.text().item.value.replace(/:/, '');
} else { } else {
let item = paramListItem.childNav.paragraph().childNav let item = paramListItem.childNav.paragraph().childNav.strong().childNav.text();
.strong().childNav.text();
if (paramName) { if (paramName) {
paramName = item.value; paramName = item.value;
} }
} }
const paramDoc = paramListItem.childNav const paramDoc = paramListItem.childNav.paragraph().childNav.text((t) => true, 1).value; // item.value;
.paragraph().childNav
.text(t => true, 1).value; // item.value;
result[paramName] = paramDoc.replace(/^[ -]+/, ''); result[paramName] = paramDoc.replace(/^[ -]+/, '');
}); });
@ -231,7 +208,7 @@ function getMDMethodParams(methItem: MDNav) {
} }
function updatePropDocsFromMD(comp: ComponentInfo, inputDocs, outputDocs, errorMessages) { function updatePropDocsFromMD(comp: ComponentInfo, inputDocs, outputDocs, errorMessages) {
comp.properties.forEach(prop => { comp.properties.forEach((prop) => {
let propMDDoc: string; let propMDDoc: string;
if (prop.isInput) { if (prop.isInput) {
@ -249,7 +226,7 @@ function updatePropDocsFromMD(comp: ComponentInfo, inputDocs, outputDocs, errorM
} }
function updateMethodDocsFromMD(comp: ComponentInfo, methodDocs, errorMessages) { function updateMethodDocsFromMD(comp: ComponentInfo, methodDocs, errorMessages) {
comp.methods.forEach(meth => { comp.methods.forEach((meth) => {
const currMethMD = methodDocs[meth.name]; const currMethMD = methodDocs[meth.name];
// If JSDocs are empty but MD docs aren't then the Markdown is presumably more up-to-date. // If JSDocs are empty but MD docs aren't then the Markdown is presumably more up-to-date.
@ -258,7 +235,7 @@ function updateMethodDocsFromMD(comp: ComponentInfo, methodDocs, errorMessages)
errorMessages.push(`Warning: empty JSDocs for method sig "${meth.name}" may need sync with the .md file.`); errorMessages.push(`Warning: empty JSDocs for method sig "${meth.name}" may need sync with the .md file.`);
} }
meth.params.forEach(param => { meth.params.forEach((param) => {
if (!param.docText && currMethMD && currMethMD.params[param.name]) { if (!param.docText && currMethMD && currMethMD.params[param.name]) {
param.docText = currMethMD.params[param.name]; param.docText = currMethMD.params[param.name];
errorMessages.push(`Warning: empty JSDocs for parameter "${param.name} (${meth.name})" may need sync with the .md file.`); errorMessages.push(`Warning: empty JSDocs for parameter "${param.name} (${meth.name})" may need sync with the .md file.`);

42
tools/doc/tools/tutorialIndex.ts
View File

@ -40,13 +40,13 @@ function aggPhase() {
const template = ejs.compile(templateSource); const template = ejs.compile(templateSource);
let mdText = template(indexDocData); let mdText = template(indexDocData);
mdText = mdText.replace(/^ +\|/mg, '|'); mdText = mdText.replace(/^ +\|/gm, '|');
const newSection = remark().use(frontMatter, ['yaml']).data('settings', {paddedTable: false, gfm: false}).parse(mdText.trim()).children; const newSection = remark().use(frontMatter, ['yaml']).data('settings', { paddedTable: false, gfm: false }).parse(mdText.trim()).children;
const tutIndexFile = path.resolve(tutFolder, 'README.md'); const tutIndexFile = path.resolve(tutFolder, 'README.md');
const tutIndexText = fs.readFileSync(tutIndexFile, 'utf8'); const tutIndexText = fs.readFileSync(tutIndexFile, 'utf8');
const tutIndexMD = remark().use(frontMatter, ['yaml']).data('settings', {paddedTable: false, gfm: false}).parse(tutIndexText); const tutIndexMD = remark().use(frontMatter, ['yaml']).data('settings', { paddedTable: false, gfm: false }).parse(tutIndexText);
replaceSection(tutIndexMD, 'Tutorials', (before, section, after) => { replaceSection(tutIndexMD, 'Tutorials', (before, section, after) => {
newSection.unshift(before); newSection.unshift(before);
@ -54,7 +54,10 @@ function aggPhase() {
return newSection; return newSection;
}); });
fs.writeFileSync(tutIndexFile, remark().use(frontMatter, {type: 'yaml', fence: '---'}).data('settings', {paddedTable: false, gfm: false}).stringify(tutIndexMD)); fs.writeFileSync(
tutIndexFile,
remark().use(frontMatter, { type: 'yaml', fence: '---' }).data('settings', { paddedTable: false, gfm: false }).stringify(tutIndexMD)
);
} }
function getIndexDocData() { function getIndexDocData() {
@ -62,7 +65,7 @@ function getIndexDocData() {
const summaryArray = JSON.parse(fs.readFileSync(indexFile, 'utf8')); const summaryArray = JSON.parse(fs.readFileSync(indexFile, 'utf8'));
let indexArray = []; let indexArray = [];
summaryArray.forEach(element => { summaryArray.forEach((element) => {
if (element['title'] === 'Tutorials') { if (element['title'] === 'Tutorials') {
indexArray = element['children']; indexArray = element['children'];
} }
@ -72,7 +75,7 @@ function getIndexDocData() {
tuts: [] tuts: []
}; };
indexArray.forEach(element => { indexArray.forEach((element) => {
const tutData = { link: element['file'] }; const tutData = { link: element['file'] };
const tutFile = path.resolve(tutFolder, element['file']); const tutFile = path.resolve(tutFolder, element['file']);
@ -89,21 +92,16 @@ function getIndexDocData() {
const briefDesc = getFirstParagraph(tutMD); const briefDesc = getFirstParagraph(tutMD);
const briefDescText = remark() tutData['briefDesc'] = remark()
.use(frontMatter, {type: 'yaml', fence: '---'}) .use(frontMatter, { type: 'yaml', fence: '---' })
.data('settings', {paddedTable: false, gfm: false}) .data('settings', { paddedTable: false, gfm: false })
.stringify(briefDesc); .stringify(briefDesc);
tutData['briefDesc'] = briefDescText;
const title = getFirstHeading(tutMD); const title = getFirstHeading(tutMD);
tutData['title'] = remark()
const titleText = remark() .use(frontMatter, { type: 'yaml', fence: '---' })
.use(frontMatter, {type: 'yaml', fence: '---'}) .data('settings', { paddedTable: false, gfm: false })
.data('settings', {paddedTable: false, gfm: false}) .stringify(title.children[0]);
.stringify(title.children[0]);
tutData['title'] = titleText;
result.tuts.push(tutData); result.tuts.push(tutData);
}); });
@ -122,11 +120,10 @@ function getDocMetadata(tree) {
function getFirstParagraph(tree) { function getFirstParagraph(tree) {
let s = 0; let s = 0;
for (; (s < tree.children.length) && !unist.isParagraph(tree.children[s]); s++) {} for (; s < tree.children.length && !unist.isParagraph(tree.children[s]); s++) {}
if (s < tree.children.length) { if (s < tree.children.length) {
return tree.children[s]; return tree.children[s];
} else { } else {
return null; return null;
} }
@ -135,11 +132,10 @@ function getFirstParagraph(tree) {
function getFirstHeading(tree) { function getFirstHeading(tree) {
let s = 0; let s = 0;
for (; (s < tree.children.length) && !unist.isHeading(tree.children[s]); s++) {} for (; s < tree.children.length && !unist.isHeading(tree.children[s]); s++) {}
if (s < tree.children.length) { if (s < tree.children.length) {
return tree.children[s]; return tree.children[s];
} else { } else {
return null; return null;
} }

127
tools/doc/tools/versionIndex.js
View File

@ -1,30 +1,20 @@
var fs = require("fs"); const fs = require('fs');
var path = require("path"); const path = require('path');
var yaml = require("js-yaml"); const yaml = require('js-yaml');
const remark = require('remark');
var remark = require("remark"); const zone = require('mdast-zone');
var stringify = require("remark-stringify"); const frontMatter = require('remark-frontmatter');
var zone = require("mdast-zone"); const ejs = require('ejs');
var frontMatter = require("remark-frontmatter"); const ngHelpers = require('../ngHelpers');
var ejs = require("ejs");
var unist = require("../unistHelpers");
var ngHelpers = require("../ngHelpers");
module.exports = { module.exports = {
"processDocs": processDocs processDocs: processDocs
}; };
const docsFolderPath = path.resolve('docs');
var docsFolderPath = path.resolve("docs"); const histFilePath = path.resolve(docsFolderPath, 'versionIndex.md');
var histFilePath = path.resolve(docsFolderPath, "versionIndex.md"); const initialVersion = 'v2.0.0';
const templateFolder = path.resolve('tools', 'doc', 'templates');
var initialVersion = "v2.0.0";
var templateFolder = path.resolve("tools", "doc", "templates");
function processDocs(mdCache, aggData) { function processDocs(mdCache, aggData) {
initPhase(aggData); initPhase(aggData);
@ -32,34 +22,29 @@ function processDocs(mdCache, aggData) {
aggPhase(aggData); aggPhase(aggData);
} }
function initPhase(aggData) { function initPhase(aggData) {
aggData.versions = { "v2.0.0":[] }; aggData.versions = { 'v2.0.0': [] };
} }
function readPhase(mdCache, aggData) { function readPhase(mdCache, aggData) {
var pathnames = Object.keys(mdCache); const pathNames = Object.keys(mdCache);
pathnames.forEach(pathname => { pathNames.forEach((pathname) => {
getFileData(mdCache[pathname].mdInTree, pathname, aggData); getFileData(mdCache[pathname].mdInTree, pathname, aggData);
}); });
} }
function getFileData(tree, pathname, aggData) { function getFileData(tree, pathname, aggData) {
var compName = pathname; const compName = pathname;
var angNameRegex = /([a-zA-Z0-9\-]+)\.((component)|(directive)|(model)|(pipe)|(service)|(widget)|(dialog))/; const angNameRegex = /([a-zA-Z0-9\-]+)\.((component)|(directive)|(model)|(pipe)|(service)|(widget)|(dialog))/;
if (!compName.match(angNameRegex)) if (!compName.match(angNameRegex)) return;
return;
if (compName.match(/boilerplate/)) if (compName.match(/boilerplate/)) return;
return;
if (tree && tree.children[0] && tree.children[0].type == "yaml") { if (tree && tree.children[0] && tree.children[0].type === 'yaml') {
var metadata = yaml.load(tree.children[0].value); const metadata = yaml.load(tree.children[0].value);
var version = metadata["Added"]; const version = metadata['Added'];
if (version) { if (version) {
if (aggData.versions[version]) { if (aggData.versions[version]) {
@ -76,40 +61,43 @@ function getFileData(tree, pathname, aggData) {
} }
function aggPhase(aggData) { function aggPhase(aggData) {
var histFileText = fs.readFileSync(histFilePath, "utf8"); const histFileText = fs.readFileSync(histFilePath, 'utf8');
var histFileTree = remark().use(frontMatter, ["yaml"]).data("settings", {paddedTable: false, gfm: false}).parse(histFileText); const histFileTree = remark()
.use(frontMatter, ['yaml'])
.data('settings', {
paddedTable: false,
gfm: false
})
.parse(histFileText);
var keys = Object.keys(aggData.versions); const keys = Object.keys(aggData.versions);
keys.sort((a, b) => { keys.sort((a, b) => {
if (a > b) if (a > b) return -1;
return -1; else if (b > a) return 1;
else if (b > a) else return 0;
return 1;
else
return 0;
}); });
var templateName = path.resolve(templateFolder, "versIndex.ejs"); const templateName = path.resolve(templateFolder, 'versIndex.ejs');
var templateSource = fs.readFileSync(templateName, "utf8"); const templateSource = fs.readFileSync(templateName, 'utf8');
var template = ejs.compile(templateSource); const template = ejs.compile(templateSource);
for (var i = 0; i < keys.length; i++) { for (let i = 0; i < keys.length; i++) {
var version = keys[i]; const version = keys[i];
var versionItems = aggData.versions[version]; const versionItems = aggData.versions[version];
versionItems.sort((a, b) => { versionItems.sort((a, b) => {
var aa = path.basename(a, ".md"); const aa = path.basename(a, '.md');
var bb = path.basename(b, ".md"); const bb = path.basename(b, '.md');
return aa.localeCompare(bb); return aa.localeCompare(bb);
}); });
var versionTemplateData = {items: []}; const versionTemplateData = { items: [] };
for (var v = 0; v < versionItems.length; v++) { for (let v = 0; v < versionItems.length; v++) {
var displayName = ngHelpers.ngNameToDisplayName(path.basename(versionItems[v], ".md")); const displayName = ngHelpers.ngNameToDisplayName(path.basename(versionItems[v], '.md'));
var pageLink = versionItems[v];// + ".md"; let pageLink = versionItems[v]; // + ".md";
pageLink = pageLink.replace(/\\/g, '/'); pageLink = pageLink.replace(/\\/g, '/');
pageLink = pageLink.substr(pageLink.indexOf("docs") + 5); pageLink = pageLink.substr(pageLink.indexOf('docs') + 5);
versionTemplateData.items.push({ versionTemplateData.items.push({
title: displayName, title: displayName,
@ -117,12 +105,18 @@ function aggPhase(aggData) {
}); });
} }
var mdText = template(versionTemplateData); let mdText = template(versionTemplateData);
mdText = mdText.replace(/^ +-/mg, "-"); mdText = mdText.replace(/^ +-/gm, '-');
var newSection = remark().use(frontMatter, ["yaml"]).data("settings", {paddedTable: false, gfm: false}).parse(mdText.trim()).children; const newSection = remark()
.use(frontMatter, ['yaml'])
.data('settings', {
paddedTable: false,
gfm: false
})
.parse(mdText.trim()).children;
var versSectionName = version.replace(/\./g, "");; const versSectionName = version.replace(/\./g, '');
zone(histFileTree, versSectionName, (startComment, oldSection, endComment) => { zone(histFileTree, versSectionName, (startComment, oldSection, endComment) => {
newSection.unshift(startComment); newSection.unshift(startComment);
@ -131,5 +125,8 @@ function aggPhase(aggData) {
}); });
} }
fs.writeFileSync(histFilePath, remark().use(frontMatter, {type: 'yaml', fence: '---'}).data("settings", {paddedTable: false, gfm: false}).stringify(histFileTree)); fs.writeFileSync(
histFilePath,
remark().use(frontMatter, { type: 'yaml', fence: '---' }).data('settings', { paddedTable: false, gfm: false }).stringify(histFileTree)
);
} }

4
tools/doc/tsconfig.json
View File

@ -11,7 +11,6 @@
"lib": ["es2018", "dom"] "lib": ["es2018", "dom"]
}, },
"files": [ "files": [
"remarkGraphQl.ts",
"mqDefs.ts", "mqDefs.ts",
"tools/fileChecker.ts", "tools/fileChecker.ts",
"tools/gqIndex.ts", "tools/gqIndex.ts",
@ -19,7 +18,6 @@
"tools/sourceLinker.ts", "tools/sourceLinker.ts",
"tools/tsInfo.ts", "tools/tsInfo.ts",
"tools/tutorialIndex.ts", "tools/tutorialIndex.ts",
"tools/typeLinker.ts", "tools/typeLinker.ts"
"reviewChecker.ts"
] ]
} }

127
tools/doc/unistHelpers.js
View File

@ -1,141 +1,82 @@
module.exports = { module.exports = {
makeRoot: function (children) {
return {
"type": "root",
"children": children
};
},
makeText: function (textVal) { makeText: function (textVal) {
return { return {
"type": "text", type: 'text',
"value": textVal value: textVal
}; };
}, },
makeEmphasis: function (content) { makeEmphasis: function (content) {
return { return {
"type": "emphasis", type: 'emphasis',
"children": content children: content
}; };
}, },
makeStrong: function (content) {
return {
"type": "strong",
"children": content
};
},
makeHeading: function (caption, depth) { makeHeading: function (caption, depth) {
return { return {
"type": "heading", type: 'heading',
"depth": depth, depth: depth,
"children": [caption] children: [caption]
}; };
}, },
makeLink: function (caption, url, title = null) { makeLink: function (caption, url, title = null) {
return { return {
"type": "link", type: 'link',
"title": title, title: title,
"url": url, url: url,
"children": [ caption ] children: [caption]
}; };
}, },
makeListItem: function (itemValue) { makeListItem: function (itemValue) {
return { return {
"type": "listItem", type: 'listItem',
"loose": false, loose: false,
"children": [ itemValue ] children: [itemValue]
}; };
}, },
makeListUnordered: function (itemsArray) { makeListUnordered: function (itemsArray) {
return { return {
"type": "list", type: 'list',
"ordered": false, ordered: false,
"children": itemsArray, children: itemsArray,
"loose": false loose: false
}; };
}, },
makeParagraph: function (itemsArray) {
return {
"type": "paragraph",
"children": itemsArray
}
},
makeTable: function (colAlignArray, rowArray) { makeTable: function (colAlignArray, rowArray) {
return { return {
"type": "table", type: 'table',
"align": colAlignArray, align: colAlignArray,
"children": rowArray children: rowArray
}; };
}, },
makeTableRow: function (cellArray) { makeTableRow: function (cellArray) {
return { return {
"type": "tableRow", type: 'tableRow',
"children": cellArray children: cellArray
}; };
}, },
makeTableCell: function (content) { makeTableCell: function (content) {
return { return {
"type": "tableCell", type: 'tableCell',
"children": content children: content
}; };
}, },
makeInlineCode: function (codeText) {
return {
"type": "inlineCode",
"value": codeText
}
},
makeHTML: function (htmlText) {
return {
"type": "html",
"value": htmlText
};
},
makeBreak: function () {
return {
"type": "break"
}
},
makeImage: function (url, alt) { makeImage: function (url, alt) {
return { return {
"type": "image", type: 'image',
"url": url, url: url,
"alt": alt alt: alt
} };
}, },
isHeading: function (node) { isHeading: function (node) {
return node.type === "heading"; return node.type === 'heading';
}, },
isListUnordered: function (node) { isListUnordered: function (node) {
return (node.type === "list") && !node.ordered; return node.type === 'list' && !node.ordered;
}, },
isParagraph: function (node) { isParagraph: function (node) {
return node.type === "paragraph"; return node.type === 'paragraph';
}, },
isText: function (node) {
return node.type === "text";
},
isLink: function (node) { isLink: function (node) {
return node.type === "inlineCode"; return node.type === 'inlineCode';
} }
} };