fix: Do not crash when typedoc "disableSources" option is true (this …

…turns off automatic module name feature)

Fixes #507

test/cypress/integration/annotations-disablesources.js

@@ -0,0 +1,121 @@
+const semver = require('semver');
+const typedocVersion = require('typedoc/package.json').version;
+const isVersion = (semverRange) => semver.satisfies(typedocVersion, semverRange);
+
+const ROOT = '/annotations-disablesources/';
+
+// Tests that tsconfig.json can use `include:` instead of `files:`
+// Not sure why when using `include:` the docs are not rendered as "tsd-is-external"
+describe('tsconfig.json with disableSources: true', () => {
+  const tsdKindModuleSelector = isVersion('> 0.17.0') ? 'li.tsd-kind-module' : 'li.tsd-kind-external-module';
+
+  it('loads', () => {
+    cy.visit('');
+  });
+
+  it('renders dir1 external', () => {
+    cy.visit(ROOT);
+    let ul = cy.get('nav.tsd-navigation.primary ul');
+    ul.get(`${tsdKindModuleSelector}.tsd-is-external`).contains('dir1');
+  });
+
+  it('renders dir2 external', () => {
+    cy.visit(ROOT);
+    let ul = cy.get('nav.tsd-navigation.primary ul');
+    ul.get(`${tsdKindModuleSelector}.tsd-is-external`).contains('dir2');
+  });
+
+  it('renders root external', () => {
+    cy.visit(ROOT);
+    let ul = cy.get('nav.tsd-navigation.primary ul');
+    ul.get(`${tsdKindModuleSelector}.tsd-is-external`).contains('root');
+  });
+
+  it('renders @preferred root documentation comment', () => {
+    cy.visit(ROOT);
+    cy.get('a').contains('root').click();
+    cy.contains('the preferred documentation for the root module');
+  });
+
+  it('renders File1 and File2 in root', () => {
+    cy.visit(ROOT);
+
+    let ul = cy.get('nav.tsd-navigation.primary ul').get('li a').contains('root').click();
+
+    if (isVersion('< 0.17.0')) {
+      cy.contains('External module root');
+    } else {
+      cy.contains('Module root');
+    }
+
+    cy.get('ul.tsd-index-list').get('a').contains('File1');
+    cy.get('ul.tsd-index-list').get('a').contains('File2');
+  });
+
+  it('renders File1 doc comment', () => {
+    cy.visit(ROOT);
+
+    cy.get('a').contains('root').click();
+    cy.get('a').contains('File1').click();
+
+    cy.contains('File1 class in the root module');
+  });
+
+  it('does not render empty comment blocks where @module used to be', () => {
+    cy.visit(ROOT);
+
+    cy.get('a').contains('dir1').click();
+    cy.get('section.tsd-comment').should('not.exist');
+  });
+
+  it('only renders the renamed modules, and none of the original names like "dir1/index"', () => {
+    cy.visit(ROOT);
+    const expectedModules = ['parent', 'dir1', 'dir2', 'root', 'dir3/nest'];
+    cy.get('.tsd-navigation').find(tsdKindModuleSelector).should('have.length', expectedModules.length);
+    expectedModules.forEach((expectedModule) => {
+      cy.get('.tsd-navigation').find(tsdKindModuleSelector).contains(expectedModule);
+    });
+  });
+
+  it('renders Nest1 in dir1', () => {
+    cy.visit(ROOT);
+
+    let ul = cy.get('nav.tsd-navigation.primary ul').get('li a').contains('dir1').click();
+
+    if (isVersion('< 0.17.0')) {
+      cy.contains('External module dir1');
+    } else {
+      cy.contains('Module dir1');
+    }
+
+    cy.get('ul.tsd-index-list').get('a').contains('Nest1');
+  });
+
+  it('renders Nest2 in dir2', () => {
+    cy.visit(ROOT);
+
+    let ul = cy.get('nav.tsd-navigation.primary ul').get('li a').contains('dir2').click();
+
+    if (isVersion('< 0.17.0')) {
+      cy.contains('External module dir2');
+    } else {
+      cy.contains('Module dir2');
+    }
+
+    cy.get('ul.tsd-index-list').get('a').contains('Nest2');
+  });
+
+  it('renders link to dir1 re-exported symbol', () => {
+    cy.get('a').contains('root').click();
+    cy.get('.tsd-member-group .tsd-signature a').contains('dir1');
+  });
+
+  it('renders modules renamed to parent.child', () => {
+    cy.get('a').contains('parent').click();
+    cy.get('a').contains('child').click();
+    cy.location().should((loc) => {
+      expect(loc.pathname).to.contain('modules/parent.child');
+    });
+    cy.get('a').contains('ParentChild');
+  });
+});

test/generate-docs.sh

@@ -4,8 +4,13 @@ echo "Generating docs..."
 function generate {
   TYPE=$1
   TSCONFIG="tsconfig.${TYPE}.json"
+  TYPEDOCCFG="typedoc.${TYPE}.json"
   echo "Copying $TSCONFIG to tsconfig.json"
-  cp tsconfig.${TYPE}.json tsconfig.json
+  cp $TSCONFIG tsconfig.json
+  [[ -f $TYPEDOCCFG ]] && {
+    echo "Copying $TYPEDOCCFG to typedoc.json"
+    cp $TYPEDOCCFG typedoc.json
+  }
   echo "Building docs into dist/${TYPE}"
 
   # Typedoc 0.9 and 0.10 required a source file on the command line
@@ -17,15 +22,12 @@ function generate {
     npx typedoc --out dist/${TYPE}
   fi
 
-  echo "Deleting tsconfig.json"
-  rm tsconfig.json
+  echo "Deleting temporary config files"
+  rm -f tsconfig.json typedoc.json
 }
 
-echo "generate annotations"
 generate annotations
-echo "generate automatic"
+generate annotations-disablesources
 generate automatic
-echo "generate automatic-nofiles"
 generate automatic-nofiles
-echo "generate custom"
 generate custom

test/package.json

@@ -24,4 +24,4 @@
   "resolutions": {
     "handlebars": "4.5.0"
   }
-}
+}

test/tsconfig.annotations-disablesources.json

@@ -0,0 +1,9 @@
+{
+  "compilerOptions": {
+    "disableSources": true,
+    "module": "commonjs",
+    "skipLibCheck": true,
+    "typeRoots": ["typings"]
+  },
+  "files": ["src/annotations/index.ts"]
+}

test/typedoc.annotations-disablesources.json

@@ -0,0 +1,3 @@
+{
+  "disableSources": true
+}

typedoc-plugin-external-module-name.ts

@@ -110,7 +110,8 @@ export class ExternalModuleNamePlugin extends ConverterComponent {
 
     /** Process options */
     const option = this.application.options.getValue('disableAutoModuleName');
-    this.disableAutoModuleName = option === 'true' || option === true;
+    const disableSources = this.application.options.getValue('disableSources');
+    this.disableAutoModuleName = option === 'true' || option === true || disableSources === true;
   }
 
   /**
@@ -126,12 +127,17 @@ export class ExternalModuleNamePlugin extends ConverterComponent {
     const preferred = /@preferred/.exec(comment) != null;
     // Look for @module
     const [, match] = /@module\s+([\w\u4e00-\u9fa5\.\-_/@"]+)/.exec(comment) || [];
-    // Make a guess based on enclosing directory structure
-    const filename = reflection.sources[0].file.fullFileName;
 
-    let guess = this.disableAutoModuleName ? undefined : path.dirname(path.relative(this.baseDir, filename));
-    if (guess === '.') {
-      guess = 'root';
+    let guess: string;
+    let filename: string;
+    if (!this.disableAutoModuleName) {
+      // Make a guess based on enclosing directory structure
+      filename = reflection.sources[0].file.fullFileName;
+      guess = this.disableAutoModuleName ? undefined : path.dirname(path.relative(this.baseDir, filename));
+
+      if (guess === '.') {
+        guess = 'root';
+      }
     }
 
     // Try the custom function