Html builder refactor

esdoc-publish-html-plugin/README.md

@@ -23,6 +23,54 @@ To use a custom template (ex `my-template` placed in the working directory):
 
 We recommend that you base on [the original template](https://github.com/esdoc/esdoc-plugins/tree/master/esdoc-publish-html-plugin/src/Builder/template).
 
+## Builder options
+
+Some of the builders have options to customize the build with.
+The defaults are listed in the example below.
+
+```json
+{
+  "name": "esdoc-publish-html-plugin",
+  "option": {
+    "template": "my-template",
+    "globalOptions": { // optional
+      "headerLinks": [ // optional
+         { "text": "Example link", "href": "local-example-page.html#some-header", "cssClass": "my-example" },
+         { "text": "Foo Bar", "href": "https://xkcd.com", "cssClass": "external-link" }
+      ]
+    },
+    "builders": {
+      "indetifiersDoc": {},
+      "indexDoc": {},
+      "classDoc": {},
+      "singleDoc": {},
+      "fileDoc": {},
+      "staticFile": {},
+      "searchIndex": {},
+      "sourceDoc": {
+        "coverageFilePath": "coverage.json"
+      },
+      "manual": {
+        "badgeFileNamePatterns": [
+            "(overview.*)",
+            "(design.*)",
+            "(installation.*)|(install.*)",
+            "(usage.*)",
+            "(configuration.*)|(config.*)",
+            "(example.*)",
+            "(faq.*)",
+            "(changelog.*)"
+        ]
+      },
+      "testDoc": {},
+      "testFileDoc": {}
+    }
+  }
+}
+```
+
+If the `builders` option is missing, all default plugins will be used with default configuration.
+
 ## LICENSE
 MIT
 

esdoc-publish-html-plugin/src/Builder/Builder.js

@@ -0,0 +1,167 @@
+/* eslint-disable max-lines */
+import fs from 'fs';
+import path from 'path';
+import IceCap from 'ice-cap';
+import NPMUtil from 'esdoc/out/src/Util/NPMUtil.js';
+
+/**
+ * Builder base class.
+ */
+export default class Builder {
+
+    /**
+     * Create builder base instance.
+     * @param {String} template - template absolute path
+     * @param {Taffy} data - doc object database.
+     * @param tags -
+     * @param builderOptions {object} - options/data specific to the builder.
+     * @param globalOptions {object} - options/data available to each builder.
+     */
+    constructor(template, data, tags, builderOptions={}, globalOptions={}) {
+        this._template = template;
+        this._data = data;
+        this._tags = tags;
+        this._builderOptions = builderOptions;
+        this._globalOptions = globalOptions;
+    }
+
+    /* eslint-disable no-unused-vars */
+    /**
+     * execute building output.
+     * @abstract
+     * @param builderUtil Utility functions to build with.
+     * @param builderUtil.writeFile {function(html: string, filePath: string)} - to write files with.
+     * @param builderUtil.copyDir {function(src: string, dest: string)} - to copy directories with.
+     * @param builderUtil.readFile {function(filePath: string): string} - to read files with.
+     */
+    exec({writeFile, copyDir, readFile}) {
+    }
+
+    /**
+     * read html template.
+     * @param {string} fileName - template file name.
+     * @return {string} html of template.
+     * @protected
+     */
+    _readTemplate(fileName) {
+        const filePath = path.resolve(this._template, `./${fileName}`);
+        return fs.readFileSync(filePath, {encoding: 'utf-8'});
+    }
+
+
+    /**
+     * get output html page title.
+     * @param {DocObject} doc - target doc object.
+     * @returns {string} page title.
+     * @protected
+     */
+    _getTitle(doc = '') {
+        const name = doc.name || doc.toString();
+
+        if (name) {
+            return `${name}`;
+        } else {
+            return '';
+        }
+    }
+
+    /**
+     * get base url html page. it is used html base tag.
+     * @param {string} fileName - output file path.
+     * @returns {string} base url.
+     * @protected
+     */
+    _getBaseUrl(fileName) {
+        return '../'.repeat(fileName.split('/').length - 1);
+    }
+
+    /**
+     * build common layout output.
+     * @return {IceCap} layout output.
+     * @protected
+     */
+    _buildLayoutDoc() {
+        const ice = new IceCap(this._readTemplate('layout.html'), {autoClose: false});
+
+        const packageObj = NPMUtil.findPackage();
+        if (packageObj) {
+            ice.text('esdocVersion', `(${packageObj.version})`);
+        } else {
+            ice.drop('esdocVersion');
+        }
+
+        ice.load('pageHeader', this._buildPageHeader());
+        ice.load('nav', this._buildNavDoc());
+        return ice;
+    }
+
+    /**
+     * build common page header output.
+     * @return {IceCap} layout output for page header.
+     * @protected
+     */
+    _buildPageHeader() {
+        const ice = new IceCap(this._readTemplate('header.html'), {autoClose: false});
+
+        let headerLinks = this._globalOptions.headerLinks;
+
+        // If there is no headerLink configuration available, then use the old behaviour:
+        //  insert default headerLinks based on available data.
+        if (!headerLinks) {
+
+            headerLinks = [];
+
+            headerLinks.push({
+                text: "Home",
+                href: "./"
+            });
+
+            const existManual = this._tags.find(tag => tag.kind.indexOf('manual') === 0);
+            const manualIndex = this._tags.find(tag => tag.kind === 'manualIndex');
+            if (!(!existManual || (manualIndex && manualIndex.globalIndex))) {
+                headerLinks.push({
+                    text: "Manual",
+                    href: "manual/index.html",
+                    cssClass: 'header-manual-link'
+                });
+            }
+            headerLinks.push({
+                text: "Reference",
+                href: "identifiers.html",
+                cssClass: 'header-reference-link'
+            });
+            headerLinks.push({
+                text: "Source",
+                href: "source.html",
+                cssClass: 'header-source-link'
+            });
+
+            const existTest = this._tags.find(tag => tag.kind.indexOf('test') === 0);
+            if (existTest) headerLinks.push({
+                text: "Test",
+                href: "test.html",
+                cssClass: 'header-test-link'
+            });
+        }
+
+        // Insert all headerLinks into the template
+        ice.loop('headerLink', headerLinks, (i, link, ice)=>{
+            ice.text('headerLink', link.text);
+            ice.attr('headerLink', 'href', link.href);
+            if (link.cssClass) ice.attr('headerLink', 'class', link.cssClass);
+        });
+
+        return ice;
+    }
+
+    /**
+     * build common page side-nave output.
+     * @return {IceCap} layout output for side-nav.
+     * @protected
+     */
+    _buildNavDoc() {
+        const html = this._readTemplate('nav.html');
+        return new IceCap(html);
+        // TODO: maybe fill nav with something by default?
+    }
+}

esdoc-publish-html-plugin/src/Builder/ClassDocBuilder.js

@@ -6,7 +6,7 @@ import {parseExample} from './util.js';
  * Class Output Builder class.
  */
 export default class ClassDocBuilder extends DocBuilder {
-  exec(writeFile) {
+  exec({writeFile}) {
     const ice = this._buildLayoutDoc();
     ice.autoDrop = false;
     const docs = this._find({kind: ['class']});

esdoc-publish-html-plugin/src/Builder/DocBuilder.js

@@ -1,37 +1,28 @@
 /* eslint-disable max-lines */
-import fs from 'fs';
 import path from 'path';
 import escape from 'escape-html';
 import IceCap from 'ice-cap';
 import {shorten, parseExample, escapeURLHash} from './util.js';
 import DocResolver from './DocResolver.js';
-import NPMUtil from 'esdoc/out/src/Util/NPMUtil.js';
+import Builder from './Builder';
 
 /**
- * Builder base class.
+ * Class for building docs.
  */
-export default class DocBuilder {
+export default class DocBuilder extends Builder {
   /**
    * create instance.
    * @param {String} template - template absolute path
    * @param {Taffy} data - doc object database.
+   * @param tags - Tag data.
+   * @param builderOptions {object} - options/data specific to the builder.
+   * @param globalOptions {object} - options/data available to each builder.
    */
-  constructor(template, data, tags) {
-    this._template = template;
-    this._data = data;
-    this._tags = tags;
+  constructor(template, data, tags, builderOptions, globalOptions) {
+    super(template, data, tags, builderOptions, globalOptions);
     new DocResolver(this).resolve();
   }
 
-  /* eslint-disable no-unused-vars */
-  /**
-   * execute building output.
-   * @abstract
-   * @param {function(html: string, filePath: string)} writeFile - is called each manual.
-   * @param {function(src: string, dest: string)} copyDir - is called asset.
-   */
-  exec(writeFile, copyDir) {
-  }
 
   /**
    * find doc object.
@@ -131,52 +122,11 @@ export default class DocBuilder {
     }
   }
 
-  /**
-   * read html template.
-   * @param {string} fileName - template file name.
-   * @return {string} html of template.
-   * @protected
-   */
-  _readTemplate(fileName) {
-    const filePath = path.resolve(this._template, `./${fileName}`);
-    return fs.readFileSync(filePath, {encoding: 'utf-8'});
-  }
-
-
-  /**
-   * build common layout output.
-   * @return {IceCap} layout output.
-   * @private
-   */
-  _buildLayoutDoc() {
-    const ice = new IceCap(this._readTemplate('layout.html'), {autoClose: false});
-
-    const packageObj = NPMUtil.findPackage();
-    if (packageObj) {
-      ice.text('esdocVersion', `(${packageObj.version})`);
-    } else {
-      ice.drop('esdocVersion');
-    }
-
-    const existTest = this._tags.find(tag => tag.kind.indexOf('test') === 0);
-    ice.drop('testLink', !existTest);
-
-    const existManual = this._tags.find(tag => tag.kind.indexOf('manual') === 0);
-    ice.drop('manualHeaderLink', !existManual);
-
-    const manualIndex = this._tags.find(tag => tag.kind === 'manualIndex');
-    if (manualIndex && manualIndex.globalIndex) {
-      ice.drop('manualHeaderLink');
-    }
-
-    ice.load('nav', this._buildNavDoc());
-    return ice;
-  }
 
   /**
    * build common navigation output.
    * @return {IceCap} navigation output.
-   * @private
+   * @protected
    */
   _buildNavDoc() {
     const html = this._readTemplate('nav.html');
@@ -503,33 +453,6 @@ export default class DocBuilder {
     return ice;
   }
 
-  /**
-   * get output html page title.
-   * @param {DocObject} doc - target doc object.
-   * @returns {string} page title.
-   * @private
-   */
-  _getTitle(doc = '') {
-    const name = doc.name || doc.toString();
-
-    if (name) {
-      return `${name}`;
-    } else {
-      return '';
-    }
-  }
-
-  /**
-   * get base url html page. it is used html base tag.
-   * @param {string} fileName - output file path.
-   * @returns {string} base url.
-   * @protected
-   */
-  _getBaseUrl(fileName) {
-    const baseUrl = '../'.repeat(fileName.split('/').length - 1);
-    return baseUrl;
-  }
-
   /**
    * gat url of output html page.
    * @param {DocObject} doc - target doc object.

esdoc-publish-html-plugin/src/Builder/FileDocBuilder.js

@@ -5,7 +5,7 @@ import DocBuilder from './DocBuilder.js';
  * File output builder class.
  */
 export default class FileDocBuilder extends DocBuilder {
-  exec(writeFile, copyDir) {
+  exec({writeFile, copyDir}) {
     const ice = this._buildLayoutDoc();
 
     const docs = this._find({kind: 'file'});

esdoc-publish-html-plugin/src/Builder/IdentifiersDocBuilder.js

@@ -7,7 +7,7 @@ import {escapeURLHash} from './util';
  * Identifier output builder class.
  */
 export default class IdentifiersDocBuilder extends DocBuilder {
-  exec(writeFile, copyDir) {
+  exec({writeFile, copyDir}) {
     const ice = this._buildLayoutDoc();
     const title = this._getTitle('Reference');
     ice.load('content', this._buildIdentifierDoc());

esdoc-publish-html-plugin/src/Builder/IndexDocBuilder.js

@@ -7,7 +7,7 @@ import {markdown} from './util.js';
  * Index output builder class.
  */
 export default class IndexDocBuilder extends DocBuilder {
-  exec(writeFile, copyDir) {
+  exec({writeFile, copyDir}) {
     const ice = this._buildLayoutDoc();
     const title = this._getTitle('Home');
     ice.load('content', this._buildIndexDoc());