docgen-tool 3.3.1 → 3.5.0

package/dist/src/docgen/views/pages/main/main.js

@@ -0,0 +1,59 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Main = void 0;
+var react_1 = __importDefault(require("react"));
+var web_table_of_contents_1 = require("../../components/web-table-of-contents/web-table-of-contents");
+var footer_1 = require("../../components/footer/footer");
+var Logo = function (_a) {
+    var parameters = _a.parameters;
+    return ((parameters === null || parameters === void 0 ? void 0 : parameters.logoPath) && (react_1.default.createElement("img", { style: {
+            marginRight: '25px',
+        }, src: parameters === null || parameters === void 0 ? void 0 : parameters.logoPath })));
+};
+var Header = function (_a) {
+    var parameters = _a.parameters;
+    return (react_1.default.createElement("header", null,
+        react_1.default.createElement("div", { className: "w-fixed-width header-container" },
+            react_1.default.createElement("div", { className: "header" },
+                react_1.default.createElement("div", { className: "headerLeftBlock" },
+                    react_1.default.createElement("a", { className: "dg-homelink", href: parameters.homePagePath },
+                        react_1.default.createElement(Logo, { parameters: parameters })),
+                    react_1.default.createElement("div", { id: "headerLeftText" },
+                        react_1.default.createElement("a", { className: "dg-homelink", href: parameters.homePagePath },
+                            react_1.default.createElement("span", { id: "dg-title" }, parameters.title),
+                            react_1.default.createElement("span", { id: "dg-web-title-version", style: { fontWeight: 'normal' } },
+                                "\u00A0(",
+                                parameters.version,
+                                ")")),
+                        react_1.default.createElement("div", { id: "headerSponsor" },
+                            react_1.default.createElement("span", null, parameters.sponsorLink.name),
+                            react_1.default.createElement("a", { href: parameters.sponsorLink.url },
+                                react_1.default.createElement("img", { id: "sponsorLogo", src: parameters.sponsorLink.logo, alt: "sponsor logo" }))))),
+                react_1.default.createElement("div", { id: "headerRightBlock" },
+                    react_1.default.createElement("span", { id: "dg-backlink" }, parameters.backlink.url && (react_1.default.createElement("a", { className: "button inverted", href: parameters.backlink.url }, parameters.backlink.name))))))));
+};
+var WebFooter = function (_a) {
+    var parameters = _a.parameters;
+    return (react_1.default.createElement("footer", null,
+        react_1.default.createElement("div", null,
+            react_1.default.createElement("p", { className: "w-fixed-width" },
+                react_1.default.createElement("span", { id: "dg-web-footer" }, parameters.webFooter))),
+        react_1.default.createElement("div", { className: "w-fixed-width" },
+            react_1.default.createElement(footer_1.Footer, { parameters: parameters }))));
+};
+var Main = function (_a) {
+    var parameters = _a.parameters, sortedPages = _a.sortedPages, pdfEnabled = _a.pdfEnabled, fixedWidth = _a.fixedWidth, children = _a.children;
+    var name = parameters.name;
+    return (react_1.default.createElement(react_1.default.Fragment, null,
+        react_1.default.createElement("div", { id: "dg-toc" },
+            react_1.default.createElement(web_table_of_contents_1.TableOfContents, { name: name, sortedPages: sortedPages, pdfEnabled: pdfEnabled })),
+        react_1.default.createElement("div", { id: "dg-navigator" }, "Table of contents"),
+        react_1.default.createElement(Header, { parameters: parameters }),
+        react_1.default.createElement("section", { id: "dg-content" }, fixedWidth ? (react_1.default.createElement("div", { className: "w-fixed-width" },
+            react_1.default.createElement("div", { id: "dg-innerContent" }, children))) : (react_1.default.createElement("div", { id: "dg-innerContent" }, children))),
+        react_1.default.createElement(WebFooter, { parameters: parameters })));
+};
+exports.Main = Main;

package/dist/src/docgen/views/pages/process-pages.js

@@ -0,0 +1,170 @@
+"use strict";
+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());
+    });
+};
+var __generator = (this && this.__generator) || function (thisArg, body) {
+    var _ = { label: 0, sent: function() { if (t[0] & 1) throw t[1]; return t[1]; }, trys: [], ops: [] }, f, y, t, g;
+    return g = { next: verb(0), "throw": verb(1), "return": verb(2) }, typeof Symbol === "function" && (g[Symbol.iterator] = function() { return this; }), g;
+    function verb(n) { return function (v) { return step([n, v]); }; }
+    function step(op) {
+        if (f) throw new TypeError("Generator is already executing.");
+        while (g && (g = 0, op[0] && (_ = 0)), _) try {
+            if (f = 1, y && (t = op[0] & 2 ? y["return"] : op[0] ? y["throw"] || ((t = y["return"]) && t.call(y), 0) : y.next) && !(t = t.call(y, op[1])).done) return t;
+            if (y = 0, t) op = [op[0] & 2, t.value];
+            switch (op[0]) {
+                case 0: case 1: t = op; break;
+                case 4: _.label++; return { value: op[1], done: false };
+                case 5: _.label++; y = op[1]; op = [0]; continue;
+                case 7: op = _.ops.pop(); _.trys.pop(); continue;
+                default:
+                    if (!(t = _.trys, t = t.length > 0 && t[t.length - 1]) && (op[0] === 6 || op[0] === 2)) { _ = 0; continue; }
+                    if (op[0] === 3 && (!t || (op[1] > t[0] && op[1] < t[3]))) { _.label = op[1]; break; }
+                    if (op[0] === 6 && _.label < t[1]) { _.label = t[1]; t = op; break; }
+                    if (t && _.label < t[2]) { _.label = t[2]; _.ops.push(op); break; }
+                    if (t[2]) _.ops.pop();
+                    _.trys.pop(); continue;
+            }
+            op = body.call(thisArg, _);
+        } catch (e) { op = [6, e]; y = 0; } finally { f = t = 0; }
+        if (op[0] & 5) throw op[1]; return { value: op[0] ? op[1] : void 0, done: true };
+    }
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.processPages = exports.processTemplates = void 0;
+var lodash_1 = require("lodash");
+var react_1 = __importDefault(require("react"));
+var picocolors_1 = __importDefault(require("picocolors"));
+var cheerio_1 = __importDefault(require("cheerio"));
+var main_1 = require("./main/main");
+var cover_1 = require("./cover/cover");
+var html_1 = require("../html");
+var pdf_cover_1 = require("./cover/pdf-cover");
+var pdf_footer_1 = require("../components/pdf-footer/pdf-footer");
+var processTemplates = function (_a) {
+    var parameters = _a.parameters, mathMathjax = _a.mathMathjax, mathKatex = _a.mathKatex, rawTemplates = _a.templates;
+    //Todo: rewrite in non-mutating style (for now just clone)
+    var templates = (0, lodash_1.cloneDeep)(rawTemplates);
+    //Todo: better way of dynamically setting template <head>
+    for (var key in templates) {
+        if (templates.hasOwnProperty(key)) {
+            var $ = templates[key];
+            $('title').text(parameters.title);
+        }
+    }
+    if (mathKatex === true) {
+        var $ = templates.main;
+        //support for KaTeX (bundled with DocGen)
+        $('head').append('<link rel="stylesheet" href="require/katex/katex.min.css" type="text/css">');
+        $('head').append('<script type="text/javascript" src="require/katex/katex.min.js"></script>');
+        $('head').append('<script type="text/javascript" src="require/katexInjector.js"></script>');
+    }
+    if (mathMathjax === true) {
+        var $ = templates.main;
+        //support for MathJax (only supported via CDN due to very large size)
+        //MathJax configuration is the same as used by math.stackexchange.com
+        //Note - wkhtmlpdf //cdn urls - see https://github.com/wkhtmltopdf/wkhtmltopdf/issues/1634
+        //Note - later than version 2 doesn't work with wkhtmltodpf
+        $('head').append("<script type=\"text/javascript\" id=\"MathJax-script\" async\n          src=\"https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.7/MathJax.js?config=TeX-MML-AM_CHTML\">\n        </script>");
+    }
+    return templates;
+};
+exports.processTemplates = processTemplates;
+var processPages = function (_a) {
+    var templates = _a.templates, rawPages = _a.pages, sortedPages = _a.sortedPages, parameters = _a.parameters, options = _a.options, contents = _a.contents;
+    return __awaiter(void 0, void 0, void 0, function () {
+        var hydratedTemplates, pages, pageTableOfContentsEnabled, tableOfContents, mainTemplate, pdfCoverTemplate, pdfFooterTemplate, webCover, pdfEnabled, webCoverHtml, $, webCoverStyles, pdfCoverHtml, $Pdf, pdfCoverStyles, pdfFooterHtml, $PdfFooter, pdfFooterStyles;
+        return __generator(this, function (_b) {
+            hydratedTemplates = (0, exports.processTemplates)({
+                parameters: parameters,
+                templates: templates,
+                mathMathjax: options.mathMathjax,
+                mathKatex: options.mathKatex,
+            });
+            pages = (0, lodash_1.cloneDeep)(rawPages);
+            pageTableOfContentsEnabled = options.pageToc;
+            tableOfContents = contents;
+            mainTemplate = hydratedTemplates.main;
+            pdfCoverTemplate = hydratedTemplates.pdfCover;
+            pdfFooterTemplate = hydratedTemplates.pdfFooter;
+            webCover = hydratedTemplates.webCover;
+            pdfEnabled = options.pdf;
+            console.log(picocolors_1.default.green('Generating the static web content'));
+            tableOfContents.forEach(function (section) {
+                section.pages.forEach(function (page) {
+                    var $ = cheerio_1.default.load(mainTemplate.html()); //clone
+                    var key = page.source;
+                    var htmlPage = (0, html_1.toHTML)(react_1.default.createElement(main_1.Main, { parameters: parameters, sortedPages: sortedPages, pdfEnabled: pdfEnabled, fixedWidth: page.html !== true }));
+                    $('body').html(htmlPage);
+                    //Todo: render the Markdown directly inside the React component
+                    var content = pages[key];
+                    $('#dg-innerContent').html(content);
+                    //------------------------------------------------------------------------------------------------------
+                    //insert permalinks for every page heading
+                    //when pageToc is enabled, also insert a page-level table of contents
+                    var html = [], i = -1;
+                    var headings = $('h1, h2, h3, h4, h5, h6');
+                    if (headings.length > 0) {
+                        html[++i] = '<ul class="dg-pageToc">';
+                    }
+                    headings.each(function () {
+                        var label = $(this).text();
+                        var anchor = label.toLowerCase().replace(/\s+/g, '-');
+                        $(this).attr('id', anchor);
+                        html[++i] = '<li><a href="#' + anchor + '">' + label + '</a></li>';
+                    });
+                    if (headings.length > 0) {
+                        html[++i] = '</ul>';
+                    }
+                    if (pageTableOfContentsEnabled === true && page.html !== true) {
+                        $('#dg-innerContent').prepend(html.join(''));
+                    }
+                    //------------------------------------------------------------------------------------------------------
+                    //prepend the auto heading (which makes the PDF table of contents match the web TOC)
+                    $('#dg-innerContent').prepend('<h1 id="dg-autoTitle">' + page.title + '</h1>');
+                    if (page.html === true) {
+                        $('#dg-autoTitle').addClass('dg-hiddenTitle');
+                    }
+                    //------------------------------------------------------------------------------------------------------
+                    //apply the w-table class
+                    $('table:not(.unstyled)').addClass('w-table w-fixed w-stripe');
+                    //------------------------------------------------------------------------------------------------------
+                    pages[key] = $.html();
+                });
+            });
+            webCoverHtml = (0, html_1.toHTML)(react_1.default.createElement(main_1.Main, { parameters: parameters, sortedPages: sortedPages, pdfEnabled: pdfEnabled },
+                react_1.default.createElement(cover_1.Cover, { parameters: parameters })));
+            $ = cheerio_1.default.load(mainTemplate.html());
+            webCoverStyles = cheerio_1.default.load(webCover.html());
+            $('head').append(webCoverStyles('head').html());
+            $('body').html(webCoverHtml);
+            pdfCoverHtml = (0, html_1.toHTML)(react_1.default.createElement(pdf_cover_1.PdfCover, { parameters: parameters }));
+            $Pdf = cheerio_1.default.load(pdfCoverTemplate.html());
+            pdfCoverStyles = cheerio_1.default.load(pdfCoverTemplate.html());
+            $Pdf('head').append(pdfCoverStyles('head').html());
+            $Pdf('body').html(pdfCoverHtml);
+            pdfFooterHtml = (0, html_1.toHTML)(react_1.default.createElement(pdf_footer_1.PdfFooter, { parameters: parameters }));
+            $PdfFooter = cheerio_1.default.load(pdfFooterTemplate.html());
+            pdfFooterStyles = cheerio_1.default.load(pdfFooterTemplate.html());
+            $PdfFooter('head').append(pdfFooterStyles('head').html());
+            $PdfFooter('body').html(pdfFooterHtml);
+            return [2 /*return*/, {
+                    pages: pages,
+                    redirect: hydratedTemplates.redirect,
+                    webCover: $.html(),
+                    pdfCover: $Pdf.html(),
+                    pdfHeader: hydratedTemplates.pdfHeader.html(),
+                    pdfFooter: $PdfFooter.html(),
+                }];
+        });
+    });
+};
+exports.processPages = processPages;

package/dist/src/docgen/views/redirect.js

@@ -0,0 +1,83 @@
+"use strict";
+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());
+    });
+};
+var __generator = (this && this.__generator) || function (thisArg, body) {
+    var _ = { label: 0, sent: function() { if (t[0] & 1) throw t[1]; return t[1]; }, trys: [], ops: [] }, f, y, t, g;
+    return g = { next: verb(0), "throw": verb(1), "return": verb(2) }, typeof Symbol === "function" && (g[Symbol.iterator] = function() { return this; }), g;
+    function verb(n) { return function (v) { return step([n, v]); }; }
+    function step(op) {
+        if (f) throw new TypeError("Generator is already executing.");
+        while (g && (g = 0, op[0] && (_ = 0)), _) try {
+            if (f = 1, y && (t = op[0] & 2 ? y["return"] : op[0] ? y["throw"] || ((t = y["return"]) && t.call(y), 0) : y.next) && !(t = t.call(y, op[1])).done) return t;
+            if (y = 0, t) op = [op[0] & 2, t.value];
+            switch (op[0]) {
+                case 0: case 1: t = op; break;
+                case 4: _.label++; return { value: op[1], done: false };
+                case 5: _.label++; y = op[1]; op = [0]; continue;
+                case 7: op = _.ops.pop(); _.trys.pop(); continue;
+                default:
+                    if (!(t = _.trys, t = t.length > 0 && t[t.length - 1]) && (op[0] === 6 || op[0] === 2)) { _ = 0; continue; }
+                    if (op[0] === 3 && (!t || (op[1] > t[0] && op[1] < t[3]))) { _.label = op[1]; break; }
+                    if (op[0] === 6 && _.label < t[1]) { _.label = t[1]; t = op; break; }
+                    if (t && _.label < t[2]) { _.label = t[2]; _.ops.push(op); break; }
+                    if (t[2]) _.ops.pop();
+                    _.trys.pop(); continue;
+            }
+            op = body.call(thisArg, _);
+        } catch (e) { op = [6, e]; y = 0; } finally { f = t = 0; }
+        if (op[0] & 5) throw op[1]; return { value: op[0] ? op[1] : void 0, done: true };
+    }
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createRedirect = void 0;
+var picocolors_1 = __importDefault(require("picocolors"));
+var path_1 = __importDefault(require("path"));
+var fs_1 = require("../fs/fs");
+var createRedirect = function (_a) {
+    var options = _a.options, redirectPage = _a.redirectPage, homePage = _a.homePage;
+    return __awaiter(void 0, void 0, void 0, function () {
+        var parent_1, homepage, redirectLink, $, file, error_1;
+        return __generator(this, function (_b) {
+            switch (_b.label) {
+                case 0:
+                    if (!options.isRedirectEnabled) return [3 /*break*/, 4];
+                    parent_1 = options.output.replace(/\/$/, '');
+                    parent_1 = parent_1.split(path_1.default.sep).slice(-1).pop(); //get name of final directory in the path
+                    homepage = homePage;
+                    homepage =
+                        homepage.source.substr(0, homepage.source.lastIndexOf('.')) + '.html';
+                    redirectLink = parent_1 + '/' + homepage;
+                    $ = redirectPage;
+                    $('a').attr('href', redirectLink);
+                    $('meta[http-equiv=REFRESH]').attr('content', '0;url=' + redirectLink);
+                    file = options.output + '../' + 'index.html';
+                    _b.label = 1;
+                case 1:
+                    _b.trys.push([1, 3, , 4]);
+                    return [4 /*yield*/, (0, fs_1.writeFile)(file, $.html())];
+                case 2:
+                    _b.sent();
+                    return [3 /*break*/, 4];
+                case 3:
+                    error_1 = _b.sent();
+                    console.log(picocolors_1.default.red('Error writing redirect file: ' + file));
+                    if (options.verbose === true) {
+                        console.log(picocolors_1.default.red(error_1));
+                    }
+                    return [3 /*break*/, 4];
+                case 4: return [2 /*return*/];
+            }
+        });
+    });
+};
+exports.createRedirect = createRedirect;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "docgen-tool",
-  "version": "3.3.1",
+  "version": "3.5.0",
   "description": "A tool for creating HTML and PDF documentation",
   "main": "dist/docgen.ts",
   "bin": {
@@ -14,14 +14,15 @@
     "dev": "ts-node src/docgen.ts run",
     "build": "rimraf dist && tsc -p tsconfig.json && yarn copy:files",
     "run:build": "dist/docgen.ts",
-    "build:docs": "ts-node src/docgen.ts run -i src/docs -o ./docs -p -m -n -d 40000",
-    "build:docs:nopdf": "ts-node src/docgen.ts run -i src/docs -m -n -o ./docs",
+    "build:docs": "ts-node src/docgen.ts run -m -n -r -p -d 40000 -i src/docs -o ./docs",
+    "build:docs:nopdf": "ts-node src/docgen.ts run -m -n -r -i src/docs -o ./docs",
     "build:styles": "sass --no-source-map src/styles/main.scss src/include/require/styles/framework.css",
     "test": "npm run prettier:check",
     "test:run": "rimraf src/__test__/test-run-output && ts-node src/docgen.ts run -i src/__test__/test-run -o src/__test__/test-run-output -p -m -n -d 40000",
+    "test:scaffold": "rimraf src/__test__/test-run-output && ts-node src/docgen.ts scaffold -o src/__test__/test-run-output",
     "test:prod:run": "rimraf src/__test__/test-run-output && ./dist/docgen.js run -i src/__test__/test-run -o ../source/__test__/test-run-output -p -m -n -d 40000",
-    "prettier:check": "prettier --check 'src/docgen.ts' '*.{js,json,css,less}'",
-    "prettier:fix": "prettier --write 'src/docgen.ts' '*.{js,json,css,less}'"
+    "prettier:check": "prettier --check 'src/docgen.ts' '*.{ts,js,json,css,less}'",
+    "prettier:fix": "prettier --write 'src/docgen.ts' '*.{ts,js,json,css,less}'"
   },
   "husky": {
     "hooks": {
@@ -33,21 +34,23 @@
     "docgen": "prettier --write"
   },
   "dependencies": {
-    "chalk": "^4.1.0",
     "cheerio": "^1.0.0-rc.12",
     "cli-spinner": "^0.2.10",
     "commander": "^11.0.0",
     "fs-extra": "^11.1.1",
     "husky": "^4.3.0",
-    "image-size": "^1.0.2",
     "lint-staged": "^10.5.1",
+    "lodash": "^4.17.21",
     "markdown-it": "^13.0.1",
-    "moment": "^2.29.4",
+    "picocolors": "^1.0.0",
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0",
     "spawn-args": "^0.2.0",
     "z-schema": "^6.0.1"
   },
   "devDependencies": {
     "@types/node": "^20.3.1",
+    "@types/react": "^18.2.37",
     "eslint": "^8.43.0",
     "eslint-config-prettier": "^8.8.0",
     "ncp": "^2.0.0",