feat(app): display project properties from package.json file

vogloblinsky · vogloblinsky · commit b091e1999eb9 · 2022-02-10T23:33:05.000+01:00
fix #1198
diff --git a/src/app/application.ts b/src/app/application.ts
@@ -233,6 +233,35 @@ export class Application {
                     }
                 }
 
+                if (!Configuration.mainData.disableProperties) {
+                    const propertiesToCheck = [
+                        'version',
+                        'description',
+                        'keywords',
+                        'homepage',
+                        'bugs',
+                        'license',
+                        'repository',
+                        'author'
+                    ];
+                    let hasOneOfCheckedProperties = false;
+                    propertiesToCheck.forEach(prop => {
+                        if (prop in parsedData) {
+                            hasOneOfCheckedProperties = true;
+                            Configuration.mainData.packageProperties[prop] = parsedData[prop];
+                        }
+                    });
+                    if (hasOneOfCheckedProperties) {
+                        Configuration.addPage({
+                            name: 'properties',
+                            id: 'packageProperties',
+                            context: 'package-properties',
+                            depth: 0,
+                            pageType: COMPODOC_DEFAULTS.PAGE_TYPES.ROOT
+                        });
+                    }
+                }
+
                 this.processMarkdowns().then(
                     () => {
                         this.getDependenciesData();
diff --git a/src/app/configuration.ts b/src/app/configuration.ts
@@ -66,6 +66,7 @@ export class Configuration implements ConfigurationInterface {
         disableRoutesGraph: COMPODOC_DEFAULTS.disableRoutesGraph,
         disableSearch: false,
         disableDependencies: COMPODOC_DEFAULTS.disableDependencies,
+        disableProperties: COMPODOC_DEFAULTS.disableProperties,
         watch: false,
         mainGraph: '',
         coverageTest: false,
@@ -84,6 +85,7 @@ export class Configuration implements ConfigurationInterface {
         customLogo: '',
         packageDependencies: [],
         packagePeerDependencies: [],
+        packageProperties: {},
         gaID: '',
         gaSite: '',
         angularProject: false,
diff --git a/src/app/engines/html-engine-helpers/capitalize.helper.ts b/src/app/engines/html-engine-helpers/capitalize.helper.ts
@@ -0,0 +1,8 @@
+import { IHtmlEngineHelper } from './html-engine-helper.interface';
+import * as Handlebars from 'handlebars';
+
+export class CapitalizeHelper implements IHtmlEngineHelper {
+    public helperFunc(context: any, text: string) {
+        return text.charAt(0).toUpperCase() + text.slice(1);
+    }
+}
diff --git a/src/app/engines/html-engine-helpers/parse-property.helper.ts b/src/app/engines/html-engine-helpers/parse-property.helper.ts
@@ -0,0 +1,12 @@
+import { IHtmlEngineHelper } from './html-engine-helper.interface';
+import * as Handlebars from 'handlebars';
+
+export class ParsePropertyHelper implements IHtmlEngineHelper {
+    public helperFunc(context: any, text: string) {
+        if (text.indexOf('https') !== -1) {
+            return `<a href="${text}" target="_blank">${text}</a>`;
+        } else {
+            return text;
+        }
+    }
+}
diff --git a/src/app/engines/html.engine.helpers.ts b/src/app/engines/html.engine.helpers.ts
@@ -3,6 +3,7 @@ import * as _ from 'lodash';
 
 import { BreakCommaHelper } from './html-engine-helpers/break-comma.helper';
 import { BreakLinesHelper } from './html-engine-helpers/break-lines.helper';
+import { CapitalizeHelper } from './html-engine-helpers/capitalize.helper';
 import { CleanParagraphHelper } from './html-engine-helpers/clean-paragraph.helper';
 import { CompareHelper } from './html-engine-helpers/compare.helper';
 import { DebugHelper } from './html-engine-helpers/debug.helper';
@@ -33,6 +34,7 @@ import { OneParameterHasHelper } from './html-engine-helpers/one-parameter-has.h
 import { OrLengthHelper } from './html-engine-helpers/or-length.helper';
 import { OrHelper } from './html-engine-helpers/or.helper';
 import { ParseDescriptionHelper } from './html-engine-helpers/parse-description.helper';
+import { ParsePropertyHelper } from './html-engine-helpers/parse-property.helper';
 import { RelativeURLHelper } from './html-engine-helpers/relative-url.helper';
 import { ShortURLHelper } from './html-engine-helpers/short-url.helper';
 import { StripURLHelper } from './html-engine-helpers/strip-url.helper';
@@ -73,10 +75,12 @@ export class HtmlEngineHelpers {
         this.registerHelper(bars, 'short-url', new ShortURLHelper());
         this.registerHelper(bars, 'strip-url', new StripURLHelper());
         this.registerHelper(bars, 't', new I18nHelper());
+        this.registerHelper(bars, 'capitalize', new CapitalizeHelper());
+        this.registerHelper(bars, 'parse-property', new ParsePropertyHelper());
     }
 
     private registerHelper(bars, key: string, helper: IHtmlEngineHelper) {
-        Handlebars.registerHelper(key, function() {
+        Handlebars.registerHelper(key, function () {
             // tslint:disable-next-line:no-invalid-this
             return helper.helperFunc.apply(helper, [this, ..._.slice(arguments as any)]);
         });
diff --git a/src/app/engines/html.engine.ts b/src/app/engines/html.engine.ts
@@ -63,7 +63,8 @@ export class HtmlEngine {
             'miscellaneous-typealiases',
             'miscellaneous-enumerations',
             'additional-page',
-            'package-dependencies'
+            'package-dependencies',
+            'package-properties'
         ];
         if (templatePath) {
             if (
diff --git a/src/app/interfaces/configuration-file.interface.ts b/src/app/interfaces/configuration-file.interface.ts
@@ -37,6 +37,7 @@ export interface ConfigurationFileInterface {
     disableRoutesGraph: boolean;
     disableSearch: boolean;
     disableDependencies: boolean;
+    disableProperties: boolean;
     minimal: boolean;
     customFavicon: string;
     customLogo: string;
diff --git a/src/app/interfaces/main-data.interface.ts b/src/app/interfaces/main-data.interface.ts
@@ -57,6 +57,7 @@ export interface MainDataInterface {
     disableRoutesGraph: boolean;
     disableSearch: boolean;
     disableDependencies: boolean;
+    disableProperties: boolean;
     watch: boolean;
     mainGraph: string;
     coverageTest: boolean;
@@ -75,6 +76,7 @@ export interface MainDataInterface {
     customLogo: string;
     packageDependencies: Object[];
     packagePeerDependencies: Object[];
+    packageProperties: any;
     gaID: string;
     gaSite: string;
     angularProject: boolean;
diff --git a/src/config/schema.json b/src/config/schema.json
@@ -284,6 +284,13 @@
             "default": false,
             "examples": [false]
         },
+        "disableProperties": {
+            "$id": "/properties/disableProperties",
+            "type": "boolean",
+            "title": "Do not add the properties list",
+            "default": false,
+            "examples": [false]
+        },
         "minimal": {
             "$id": "/properties/minimal",
             "type": "boolean",
diff --git a/src/index-cli.ts b/src/index-cli.ts
@@ -174,6 +174,11 @@ Note: Certain tabs will only be shown if applicable to a given dependency`,
                 'Do not add the dependencies list',
                 COMPODOC_DEFAULTS.disableDependencies
             )
+            .option(
+                '--disableProperties',
+                'Do not add the properties list',
+                COMPODOC_DEFAULTS.disableProperties
+            )
             .option(
                 '--minimal',
                 'Minimal mode with only documentation. No search, no graph, no coverage.',
@@ -520,6 +525,13 @@ Note: Certain tabs will only be shown if applicable to a given dependency`,
             Configuration.mainData.disableDependencies = programOptions.disableDependencies;
         }
 
+        if (configFile.disableProperties) {
+            Configuration.mainData.disableProperties = configFile.disableProperties;
+        }
+        if (programOptions.disableProperties) {
+            Configuration.mainData.disableProperties = programOptions.disableProperties;
+        }
+
         if (configFile.minimal) {
             Configuration.mainData.disableSearch = true;
             Configuration.mainData.disableRoutesGraph = true;
diff --git a/src/resources/styles/compodoc.css b/src/resources/styles/compodoc.css
@@ -1071,4 +1071,12 @@ ul.index-list {
     .dark-mode-switch {
         top: 15px;
     }
-}
+}
+
+ul.properties-list {
+    list-style: none;
+    padding-left: 0;
+}
+.properties-list li {
+    margin-bottom: 10px;
+}
diff --git a/src/templates/page.hbs b/src/templates/page.hbs
@@ -119,6 +119,12 @@
                          {{/compare}}
                     {{/unless}}
 
+                    {{#unless data.disableProperties}}
+                         {{#compare data.context "===" 'package-properties'}}
+                              {{~> package-properties data ~}}
+                         {{/compare}}
+                    {{/unless}}
+
 
                    {{#compare data.context "===" 'miscellaneous-functions'}}
                         {{~> miscellaneous-functions data ~}}
diff --git a/src/templates/partials/menu.hbs b/src/templates/partials/menu.hbs
@@ -65,6 +65,15 @@ customElements.define('compodoc-menu', class extends HTMLElement {
                                 </li>
                             {{/orLength}}
                         {{/unless}}
+                        {{#unless disableProperties}}
+                            {{#orLength packageProperties}}
+                                <li class="link">
+                                    <a href="properties.html" data-type="chapter-link">
+                                        <span class="icon ion-ios-apps"></span>{{t "properties" }}
+                                    </a>
+                                </li>
+                            {{/orLength}}
+                        {{/unless}}
                     </ul>
                 </li>
                 {{#if additionalPages}}
diff --git a/src/templates/partials/package-properties.hbs b/src/templates/partials/package-properties.hbs
@@ -0,0 +1,11 @@
+{{#if packageProperties}}
+    <ol class="breadcrumb">
+        <li>{{t "properties" }}</li>
+    </ol>
+    <ul class="properties-list">
+        {{#each packageProperties}}
+        <li>
+            <b>{{capitalize @key}}</b> : {{{parse-property this}}}</li>
+        {{/each}}
+    </ul>
+{{/if}}
diff --git a/src/utils/defaults.ts b/src/utils/defaults.ts
@@ -27,6 +27,7 @@ export const COMPODOC_DEFAULTS = {
     disableLifeCycleHooks: false,
     disableRoutesGraph: false,
     disableDependencies: false,
+    disableProperties: false,
     PAGE_TYPES: {
         ROOT: 'root',
         INTERNAL: 'internal'
diff --git a/test/fixtures/todomvc-ng2/package.json b/test/fixtures/todomvc-ng2/package.json
@@ -12,5 +12,15 @@
     "devDependencies": {
         "@compodoc/compodoc": "https://github.com/compodoc/compodoc/tarball/develop",
         "typescript": "~3.1.1"
-    }
+    },
+    "description": "Demo for project",
+    "keywords": [
+        "documentation",
+        "angular"
+    ],
+    "homepage": "https://github.com/just-a-repo",
+    "bugs": "https://github.com/just-a-repo/issues",
+    "url": "https://github.com/just-a-repo",
+    "repository": "https://github.com/just-a-repo",
+    "author": "The author"
 }
diff --git a/test/src/cli/cli-disable-options.spec.ts b/test/src/cli/cli-disable-options.spec.ts
@@ -287,7 +287,7 @@ describe('CLI disable flags', () => {
     describe('disabling dependencies with --disableDependencies', () => {
         before(function (done) {
             tmp.create(distFolder);
-            let ls = shell('node', [
+            const ls = shell('node', [
                 './bin/index-cli.js',
                 '-p',
                 './test/fixtures/sample-files/tsconfig.simple.json',
@@ -305,11 +305,37 @@ describe('CLI disable flags', () => {
         after(() => tmp.clean(distFolder));
 
         it('should not generate the dependencies list', () => {
-            let file = read(`${distFolder}/js/menu-wc.js`);
+            const file = read(`${distFolder}/js/menu-wc.js`);
             expect(file).not.to.contain('href="dependencies.html"');
         });
     });
 
+    describe('disabling properties with --disableProperties', () => {
+        before(function (done) {
+            tmp.create(distFolder);
+            const ls = shell('node', [
+                './bin/index-cli.js',
+                '-p',
+                './test/fixtures/sample-files/tsconfig.simple.json',
+                '--disableProperties',
+                '-d',
+                distFolder
+            ]);
+
+            if (ls.stderr.toString() !== '') {
+                console.error(`shell error: ${ls.stderr.toString()}`);
+                done('error');
+            }
+            done();
+        });
+        after(() => tmp.clean(distFolder));
+
+        it('should not generate the properties list', () => {
+            const file = read(`${distFolder}/js/menu-wc.js`);
+            expect(file).not.to.contain('href="properties.html"');
+        });
+    });
+
     describe('minimal with --minimal', () => {
         let fileContents;
 
diff --git a/test/src/cli/cli-generation-big-app.spec.ts b/test/src/cli/cli-generation-big-app.spec.ts
@@ -584,6 +584,15 @@ describe('CLI simple generation - big app', () => {
         expect(dependencies).to.contain('angular/forms');
     });
 
+    it('should display project properties', () => {
+        const file = exists(distFolder + '/properties.html');
+        expect(file).to.be.true;
+        const properties = read(distFolder + '/properties.html');
+        expect(properties).to.contain('Demo for project');
+        expect(properties).to.contain('The author');
+        expect(properties).to.contain('https://github.com/just-a-repo');
+    });
+
     it('should display project local TypeScript version', () => {
         expect(stdoutString).to.contain('TypeScript version of current project');
     });
