Updated specs

package.json

@@ -13,6 +13,7 @@
     "@types/fs-extra": "^9.0.1",
     "@types/jest": "^26.0.10",
     "@types/node": "^14.6.2",
+    "@types/tmp": "^0.2.0",
     "@typescript-eslint/eslint-plugin": "^3.10.1",
     "@typescript-eslint/parser": "^3.10.1",
     "copyfiles": "^2.3.0",
@@ -21,6 +22,7 @@
     "lerna": "^3.22.1",
     "npm-run-all": "^4.1.5",
     "prettier": "^2.1.1",
+    "tmp": "^0.2.1",
     "ts-jest": "^26.3.0"
   }
 }

packages/typedoc-plugin-markdown/README.md

@@ -9,8 +9,7 @@ A plugin for [TypeDoc](https://github.com/TypeStrong/typedoc) that enables TypeS
 
 The plugin will replace the default HTML theme with a built-in Markdown theme, and expose some additional arguments.
 
-By default, the Markdown theme will attempt to render standard CommonMark, suitable for the majority of Markdown engines.
-It follows the same structure and file patterns as the default HTML theme.
+Please not if using Docusaurus or Vuepress xxx.
 
 ## Installation
 
@@ -34,16 +33,32 @@ $ npx typedoc --plugin typedoc-plugin-markdown [args]
 
 The following arguments can be used in addition to the default [TypeDoc arguments](https://github.com/TypeStrong/typedoc#arguments).
 
-- `--theme <markdown|path/to/custom/theme>`<br>
-  Defaults to `markdown`. See [custom themes](https://github.com/tgreyuk/typedoc-plugin-markdown/blob/master/packages/typedoc-plugin-markdown/THEMES.md) for further details.
-- `--namedAnchors`<br>
-  Use HTML named anchors as fragment identifiers for engines that do not automatically assign header ids.
-- `--hideSources`<br>
-  Do not print source file link rendering.
-- `--hideBreadcrumbs`<br>
-  Do not print breadcrumbs.
-- `--publicPath`<br>
-- Specifies the base path for all urls. If omitted urls will be relative.
+- `--defaultFileName<string>`<br>
+  Specify the filename of the index/entry page (ext not required). Defaults to `README`.
+- `--hideBreadcrumbs<boolean>`<br>
+  Do not render breadcrumbs. Defaults to `false`.
+- `--hideIndexes<boolean>`<br>
+  Do not render page indexes. Defaults to `false`.
+- `--publicPath<string>`<br>
+  Specify the base path for all urls. If undefined urls will be relative. Defaults to `undefined`.
+
+**Anchor links**
+
+The following options can be ignored with the majority of implementations.
+
+- `--namedAnchors<boolean>`<br>
+  Use HTML named anchors tags for implementations that do not automatically assign header ids.
+- `--bitbucketCloudAnchors<boolean>`<br>
+  Fix anchors in Bitbucket Cloud which escapes all HTML and implements a proprietry anchor linking implementation.
+
+## Additional plugins
+
+- docusaurus-plugin-typedoc
+- vuepress-plugin-typedoc
+
+## Theme customisation
+
+## Version 3
 
 ## License
 

packages/typedoc-plugin-markdown/demo.options.json

@@ -1,8 +1,8 @@
 {
-  "inputFiles": "../../ts-samples/demo/basic/src",
+  "inputFiles": "./test/stubs/src",
   "target": "ES5",
   "name": "My API",
-  "readme": "none",
+
   "includes": "./test/stubs/inc/",
   "media": "./test/stubs/media/",
   "ignoreCompilerErrors": true

packages/typedoc-plugin-markdown/package.json

@@ -10,7 +10,7 @@
     "lint": "eslint ./src --ext .ts",
     "prepublishOnly": "npm run lint && npm run build && npm run test",
     "build": "rm -rf dist && tsc && copyfiles --up 1 ./src/**/*.hbs ./dist/",
-    "test": "jest --colors",
+    "test": "jest --updateSnapshot --colors",
     "test:update": "jest --updateSnapshot",
     "build-and-test": "npm run build && npm run test",
     "fixtures": "node ./tasks/fixtures.js",
@@ -21,7 +21,7 @@
   "author": "Thomas Grey",
   "license": "MIT",
   "engines": {
-    "node": ">= 8.0.0"
+    "node": ">=10.0.0"
   },
   "bugs": {
     "url": "https://github.com/tgreyuk/typedoc-plugin-markdown/issues"
@@ -41,14 +41,14 @@
     "typedoc"
   ],
   "peerDependencies": {
-    "typedoc": ">=0.17.0"
+    "typedoc": ">=0.19.0"
   },
   "dependencies": {
     "fs-extra": "^9.0.1",
     "handlebars": "^4.7.6"
   },
   "devDependencies": {
-    "typedoc": "^0.18.0",
-    "typescript": "^3.9.7"
+    "typedoc": "^0.19.0",
+    "typescript": "^4.0.2"
   }
 }

packages/typedoc-plugin-markdown/src/__snapshots__/theme.spec.ts.snap

@@ -3,9 +3,35 @@
 exports[`theme getUrls should getUrls' 1`] = `
 Array [
   "README.md",
+  "modules/_categories_.md",
   "modules/_classes_.md",
   "modules/_comments_.md",
+  "modules/_functions_.md",
+  "modules/_interfaces_.md",
+  "modules/_literals_.md",
+  "modules/_reflection_.md",
   "modules/_variables_.md",
+  "modules/_categories_.md",
+  "interfaces/_categories_.categoryinterfacea1.md",
+  "interfaces/_categories_.categoryinterfacea2.md",
+  "interfaces/_categories_.otherinterfacea.md",
+  "modules/_categories_.md#categoryvariablea1",
+  "modules/_categories_.md#categoryvariablea2",
+  "modules/_categories_.md#categoryvariableb1",
+  "modules/_categories_.md#othervariablea",
+  "modules/_categories_.md#othervariableb",
+  "modules/_categories_.md#categoryfunctiona1",
+  "modules/_categories_.md#categoryfunctiona2",
+  "modules/_categories_.md#categoryfunctiona3",
+  "modules/_categories_.md#categoryfunctionb2",
+  "modules/_categories_.md#otherfunctiona",
+  "modules/_categories_.md#otherfunctionb",
+  "interfaces/_categories_.categoryinterfacea1.md",
+  "interfaces/_categories_.categoryinterfacea1.md#value",
+  "interfaces/_categories_.categoryinterfacea2.md",
+  "interfaces/_categories_.categoryinterfacea2.md#value",
+  "interfaces/_categories_.otherinterfacea.md",
+  "interfaces/_categories_.otherinterfacea.md#value",
   "modules/_classes_.md",
   "classes/_classes_.greeter.md",
   "modules/_classes_.md#greeter",
@@ -20,6 +46,42 @@ Array [
   "modules/_comments_.md#commentswithsymbollinks",
   "modules/_comments_.md#commentswithtags",
   "modules/_comments_.md#commentsinreturn",
+  "modules/_functions_.md",
+  "modules/_functions_.md#buildname",
+  "modules/_functions_.md#functionwithdefaults",
+  "modules/_functions_.md#functionwithoptionalvalue",
+  "modules/_functions_.md#functionwithparameters",
+  "modules/_functions_.md#functionwithrest",
+  "modules/_functions_.md#modulefunction",
+  "modules/_functions_.md#multiplesignatures",
+  "modules/_functions_.md#restuntiontypes",
+  "modules/_functions_.md#variablefunction",
+  "modules/_interfaces_.md",
+  "modules/_literals_.md",
+  "modules/_literals_.md#easing",
+  "modules/_literals_.md#result",
+  "modules/_literals_.md#typeliteral",
+  "modules/_literals_.md#typeliteral2",
+  "modules/_literals_.md#rolldice",
+  "modules/_literals_.md#objectliteral",
+  "modules/_literals_.md#objectliteral2",
+  "modules/_reflection_.md",
+  "classes/_reflection_.childclassa.md",
+  "classes/_reflection_.childclassb.md",
+  "classes/_reflection_.parentclass.md",
+  "interfaces/_reflection_.callableinterface.md",
+  "interfaces/_reflection_.indexableinterface.md",
+  "interfaces/_reflection_.typeparamsinterface.md",
+  "classes/_reflection_.childclassa.md",
+  "classes/_reflection_.childclassa.md#prop",
+  "classes/_reflection_.childclassb.md",
+  "classes/_reflection_.childclassb.md#prop",
+  "classes/_reflection_.parentclass.md",
+  "classes/_reflection_.parentclass.md#prop",
+  "interfaces/_reflection_.callableinterface.md",
+  "interfaces/_reflection_.indexableinterface.md",
+  "interfaces/_reflection_.typeparamsinterface.md",
+  "interfaces/_reflection_.typeparamsinterface.md#prop",
   "modules/_variables_.md",
   "modules/_variables_.md#color",
   "modules/_variables_.md#decimal",

packages/typedoc-plugin-markdown/src/resources/helpers/__snapshots__/declaration-title.spec.ts.snap

@@ -0,0 +1,3 @@
+// Jest Snapshot v1, https://goo.gl/fbAQLP
+
+exports[`[helpers] declarationTitle should compile 1`] = `"\`Const\`  **color**: \\"blue\\"  = \\"blue\\""`;

packages/typedoc-plugin-markdown/src/resources/helpers/__snapshots__/signature-title.spec.ts.snap

@@ -0,0 +1,6 @@
+// Jest Snapshot v1, https://goo.gl/fbAQLP
+
+exports[`[helpers] signatureTitle should compile 1`] = `
+"**functionWithParameters**(\`paramZ\`: string, \`paramG\`: any, \`paramA\`: any): *number*
+"
+`;

packages/typedoc-plugin-markdown/src/resources/helpers/__snapshots__/strip-line-breaks.spec.ts.snap

@@ -0,0 +1,3 @@
+// Jest Snapshot v1, https://goo.gl/fbAQLP
+
+exports[`[helpers] stripLineBreaks should compile : line 1  line2 1`] = `"line 1  line2 "`;

packages/typedoc-plugin-markdown/src/resources/helpers/declaration-title.spec.ts

@@ -0,0 +1,19 @@
+import * as Handlebars from 'handlebars';
+
+import { TestApp } from '../../../test/utils';
+
+describe(`[helpers] declarationTitle`, () => {
+  let testApp: TestApp;
+  beforeAll(() => {
+    testApp = new TestApp(['variables']);
+    testApp.bootstrap();
+  });
+
+  test(`should compile`, () => {
+    expect(
+      Handlebars.helpers.declarationTitle.call(
+        testApp.project.findReflectionByName('color'),
+      ),
+    ).toMatchSnapshot();
+  });
+});

packages/typedoc-plugin-markdown/src/resources/helpers/signature-title.spec.ts

@@ -0,0 +1,18 @@
+import * as Handlebars from 'handlebars';
+
+import { TestApp } from '../../../test/utils';
+
+describe(`[helpers] signatureTitle`, () => {
+  let testApp: TestApp;
+  beforeAll(() => {
+    testApp = new TestApp(['functions']);
+    testApp.bootstrap();
+  });
+  test(`should compile`, () => {
+    const data = testApp.project.findReflectionByName(
+      'functionWithParameters',
+    ) as any;
+    const result = Handlebars.helpers.signatureTitle.call(data.signatures[0]);
+    expect(result).toMatchSnapshot();
+  });
+});

packages/typedoc-plugin-markdown/src/resources/helpers/strip-line-breaks.spec.ts

@@ -0,0 +1,7 @@
+import { stripLineBreaks } from './strip-line-breaks';
+describe(`[helpers] stripLineBreaks`, () => {
+  test(`should compile `, () => {
+    const result = stripLineBreaks.call('line 1\n line2\n');
+    expect(result).toMatchSnapshot('line 1  line2');
+  });
+});

packages/typedoc-plugin-markdown/src/resources/templates/__snapshots__/reflection.spec.ts.snap

@@ -0,0 +1,75 @@
+// Jest Snapshot v1, https://goo.gl/fbAQLP
+
+exports[`[template] reflection.hbs should compile a callable reflection 1`] = `
+"## Hierarchy
+
+[partial: hierarchy]
+
+## Callable
+
+[partial: member.signature]
+
+[partial: index]
+
+[partial: members]
+"
+`;
+
+exports[`[template] reflection.hbs should compile an indexable reflection 1`] = `
+"## Hierarchy
+
+[partial: hierarchy]
+
+## Indexable
+
+[partial: member.indexSignatures]
+
+[partial: index]
+
+[partial: members]
+"
+`;
+
+exports[`[template] reflection.hbs should compile reflection with type params / implemented by 1`] = `
+"[partial: comment]
+
+## Type parameters
+
+[partial: typeParameters]
+
+## Hierarchy
+
+[partial: hierarchy]
+
+## Implemented by
+
+* [helper: type]
+* [helper: type]
+* [helper: type]
+
+[partial: index]
+
+[partial: members]
+"
+`;
+
+exports[`[template] reflection.hbs should compile reflection without index 1`] = `
+"[partial: comment]
+
+## Type parameters
+
+[partial: typeParameters]
+
+## Hierarchy
+
+[partial: hierarchy]
+
+## Implemented by
+
+* [helper: type]
+* [helper: type]
+* [helper: type]
+
+[partial: members]
+"
+`;

packages/typedoc-plugin-markdown/src/resources/templates/reflection.spec.ts

@@ -0,0 +1,66 @@
+import * as path from 'path';
+
+import * as fs from 'fs-extra';
+import * as Handlebars from 'handlebars';
+
+import {
+  TestApp,
+  compileHandlabrs,
+  stubHelpers,
+  stubPartials,
+} from '../../../test/utils';
+
+describe(`[template] reflection.hbs`, () => {
+  let testApp: TestApp;
+  let template: Handlebars.TemplateDelegate;
+
+  beforeAll(() => {
+    testApp = new TestApp(['reflections']);
+    testApp.bootstrap(false);
+    stubPartials();
+    stubHelpers();
+    const partial = fs.readFileSync(path.resolve(__dirname, 'reflection.hbs'));
+    template = Handlebars.compile(partial.toString());
+  });
+
+  beforeEach(() => {
+    Handlebars.registerHelper('ifShowIndexes', (options) => options.fn());
+  });
+
+  test(`should compile reflection with type params / implemented by`, () => {
+    expect(
+      compileHandlabrs(
+        template,
+        testApp.project.findReflectionByName('TypeParamsInterface'),
+      ),
+    ).toMatchSnapshot();
+  });
+
+  test(`should compile a callable reflection`, () => {
+    expect(
+      compileHandlabrs(
+        template,
+        testApp.project.findReflectionByName('CallableInterface'),
+      ),
+    ).toMatchSnapshot();
+  });
+
+  test(`should compile an indexable reflection`, () => {
+    expect(
+      compileHandlabrs(
+        template,
+        testApp.project.findReflectionByName('IndexableInterface'),
+      ),
+    ).toMatchSnapshot();
+  });
+
+  test(`should compile reflection without index`, () => {
+    Handlebars.registerHelper('ifShowIndexes', (options) => options.inverse());
+    expect(
+      compileHandlabrs(
+        template,
+        testApp.project.findReflectionByName('TypeParamsInterface'),
+      ),
+    ).toMatchSnapshot();
+  });
+});

packages/typedoc-plugin-markdown/tasks/fixtures.js

@@ -12,7 +12,7 @@ const app = new Application({
 });
 
 const fixturesDir = './test/fixtures';
-const inputFiles = app.expandInputFiles(['../../ts-samples/demo/basic/src/interfaces.ts']);
+const inputFiles = app.expandInputFiles(['./test/stubs/src']);
 
 if (!fs.existsSync(fixturesDir)) {
   fs.mkdirSync(fixturesDir);
@@ -20,8 +20,15 @@ if (!fs.existsSync(fixturesDir)) {
 
 inputFiles.forEach((file) => {
   const result = app.convert(app.expandInputFiles([file]));
-  fs.writeFileSync(`${fixturesDir}/${path.basename(file)}.json`, JSON.stringify(result, replacer));
-  console.log(`[typedoc-plugin-markdown(task:fixtures)] writing ${path.basename(file)}.json fixture`);
+  fs.writeFileSync(
+    `${fixturesDir}/${path.basename(file)}.json`,
+    JSON.stringify(result, replacer),
+  );
+  console.log(
+    `[typedoc-plugin-markdown(task:fixtures)] writing ${path.basename(
+      file,
+    )}.json fixture`,
+  );
 });
 
 function replacer(key, value) {

packages/typedoc-plugin-markdown/test/stubs/src/interfaces.ts

@@ -1,35 +1 @@
-interface SquareConfig {
-  /**
-   * The color of the square
-   */
-  color: string;
-  width?: number;
-  border?: number;
-  borderColor?: string;
-}
 
-function createSquare(config: SquareConfig): { color: string; area: number } {
-  const newSquare = { color: 'white', area: 100 };
-  if (config.color) {
-    newSquare.color = config.color;
-  }
-  if (config.width) {
-    newSquare.area = config.width * config.width;
-  }
-  return newSquare;
-}
-
-const mySquare = createSquare({ color: 'black' });
-
-interface ClockInterface {
-  currentTime: Date;
-  setTime(d: Date): void;
-}
-
-class Clock implements ClockInterface {
-  currentTime: Date = new Date();
-  setTime(d: Date) {
-    this.currentTime = d;
-  }
-  constructor(h: number, m: number) {}
-}

packages/typedoc-plugin-markdown/test/stubs/src/reflection.ts

@@ -0,0 +1,26 @@
+// type params / implemented by / comments
+/**
+ * Comments
+ */
+interface TypeParamsInterface<T> {
+  prop: T;
+}
+
+// callable
+export interface CallableInterface {
+  (): string;
+}
+
+// indexable
+export interface IndexableInterface {
+  [index: number]: string;
+}
+
+// implements
+export class ParentClass implements TypeParamsInterface<string> {
+  prop = 'hello world';
+}
+
+// extends
+export class ChildClassA extends ParentClass {}
+export class ChildClassB extends ParentClass {}

packages/typedoc-plugin-markdown/test/stubs/src/variables.ts

@@ -1,15 +1,15 @@
-let isDone: boolean = false;
+const isDone = false;
 
-let decimal: number = 6;
+const decimal = 6;
 
-let color: string = 'blue';
+const color = 'blue';
 
-let list: number[] = [1, 2, 3];
+const list: number[] = [1, 2, 3];
 
 let x: [string, number];
 
-let notSure: any = 4;
+const notSure: any = 4;
 
 let u: undefined;
 
-let n: null = null;
+const n = null;

packages/typedoc-plugin-markdown/test/utils.ts

@@ -1,25 +1,32 @@
 import * as path from 'path';
 
+import * as fs from 'fs-extra';
+import * as Handlebars from 'handlebars';
+import * as tmp from 'tmp';
 import { Application, ProjectReflection, Renderer } from 'typedoc';
 import { ModuleKind, ScriptTarget } from 'typescript';
 
 import MarkdownTheme from '../src/theme';
 
+tmp.setGracefulCleanup();
+
 export class TestApp {
   app: Application;
   inputFiles: string[];
   project: ProjectReflection;
   renderer: Renderer;
   theme: MarkdownTheme;
+  outDir: string;
+  tmpobj: tmp.DirResult;
 
   constructor(files?: string[]) {
     this.app = new Application();
     this.inputFiles = files
-      ? files.map((file) => './test/stubs/src/' + file + '.ts')
+      ? files.map((file) => './test/stubs/src/')
       : ['./test/stubs/'];
   }
 
-  bootstrap(options = {}) {
+  bootstrap(options = {}, generate = true) {
     this.app.bootstrap({
       module: ModuleKind.CommonJS,
       target: ScriptTarget.ES5,
@@ -29,12 +36,14 @@ export class TestApp {
       plugin: [path.join(__dirname, '../dist/index')],
       ...options,
     });
+
     this.project = this.app.convert(this.app.expandInputFiles(this.inputFiles));
-    //if (generate) {
-    this.app.generateDocs(this.project, path.join(__dirname, 'tmp'));
-    //}
-    this.theme = this.app.renderer.theme as MarkdownTheme;
-    this.renderer = this.app.renderer;
+    if (generate) {
+      this.tmpobj = tmp.dirSync();
+      this.app.generateDocs(this.project, this.tmpobj.name);
+      this.theme = this.app.renderer.theme as MarkdownTheme;
+      this.renderer = this.app.renderer;
+    }
   }
 
   convert() {
@@ -44,6 +53,11 @@ export class TestApp {
   getComponent(component: string) {
     return this.app.renderer.getComponent(component);
   }
+
+  getDoc(file: string) {
+    const result = fs.readFileSync(this.tmpobj.name + file);
+    return result.toString();
+  }
 }
 
 export const handlebarsOptionsStub = {
@@ -51,3 +65,33 @@ export const handlebarsOptionsStub = {
   inverse: () => false,
   hash: {},
 };
+
+export const stubPartials = () => {
+  [
+    'index',
+    'comment',
+    'hierarchy',
+    'members',
+    'implements',
+    'member.signature',
+    'member.indexSignatures',
+    'typeParameters',
+  ].forEach((partial) => {
+    Handlebars.registerPartial(partial, `[partial: ${partial}]`);
+  });
+};
+
+export const stubHelpers = () => {
+  Handlebars.registerHelper('type', () => '[helper: type]');
+};
+
+export const compileHandlabrs = (template, model) =>
+  MarkdownTheme.formatContents(
+    template(
+      { model },
+      {
+        allowProtoMethodsByDefault: true,
+        allowProtoPropertiesByDefault: true,
+      },
+    ),
+  );

yarn.lock

@@ -1527,6 +1527,11 @@
   resolved "https://registry.yarnpkg.com/@types/tapable/-/tapable-1.0.6.tgz#a9ca4b70a18b270ccb2bc0aaafefd1d486b7ea74"
   integrity sha512-W+bw9ds02rAQaMvaLYxAbJ6cvguW/iJXNT6lTssS1ps6QdrMKttqEAMEG/b5CR8TZl3/L7/lH0ZV5nNR1LXikA==
 
+"@types/tmp@^0.2.0":
+  version "0.2.0"
+  resolved "https://registry.yarnpkg.com/@types/tmp/-/tmp-0.2.0.tgz#e3f52b4d7397eaa9193592ef3fdd44dc0af4298c"
+  integrity sha512-flgpHJjntpBAdJD43ShRosQvNC0ME97DCfGvZEDlAThQmnerRXrLbX6YgzRBQCZTthET9eAWFAMaYP0m0Y4HzQ==
+
 "@types/uglify-js@*":
   version "3.9.3"
   resolved "https://registry.yarnpkg.com/@types/uglify-js/-/uglify-js-3.9.3.tgz#d94ed608e295bc5424c9600e6b8565407b6b4b6b"
@@ -7132,6 +7137,13 @@ tmp@^0.0.33:
   dependencies:
     os-tmpdir "~1.0.2"
 
+tmp@^0.2.1:
+  version "0.2.1"
+  resolved "https://registry.yarnpkg.com/tmp/-/tmp-0.2.1.tgz#8457fc3037dcf4719c251367a1af6500ee1ccf14"
+  integrity sha512-76SUhtfqR2Ijn+xllcI5P1oyannHNHByD80W1q447gU3mp9G9PSpGdWmjUOHRDPiHYacIk66W7ubDTuPF3BEtQ==
+  dependencies:
+    rimraf "^3.0.0"
+
 tmpl@1.0.x:
   version "1.0.4"
   resolved "https://registry.yarnpkg.com/tmpl/-/tmpl-1.0.4.tgz#23640dd7b42d00433911140820e5cf440e521dd1"