0xproject / ts-doc-gen

A CLI for generating a single MD reference doc file for a TS project

@0x/ts-doc-gen

A CLI for generating a single MD reference doc file for a TS project

Installation

yarn add @0x/ts-doc-gen

Install dependencies

yarn install

Build

yarn build

Clean

yarn clean

Lint

yarn lint

ts-doc-gen's Issues

Support TypeDoc v0.16.11

Description

This tool will crash with an error when using the latest version of TypeDoc, v0.16.11, when the TypeDoc configuration file is omitted. Since @0x/ts-doc-gen has a dependency of TypeDoc v^0.15.0, this can't necessarily be considered a bug; however, the latest releases of TypeDoc contain some improvements that would be worth supporting in @0x/ts-doc-gen.

Expected Behavior

Generates TypeDoc v0.16.11 documentation.

Actual Behavior

Crashes with the following error:

typedoc command failed:  { Error: Command failed: ./node_modules/.bin/typedoc --theme markdown --platform gitbook --ignoreCompilerErrors --excludePrivate --excludeProtected --excludeExternals --excludeNotExported --target ES5 --module commonjs --hideGenerator --out ../../docs/browser-bindings/browser src

    at ChildProcess.exithandler (child_process.js:299:12)
    at ChildProcess.emit (events.js:193:13)
    at maybeClose (internal/child_process.js:999:16)
    at Process.ChildProcess._handle.onexit (internal/child_process.js:266:5)
  killed: false,
  code: 1,
  signal: null,
  cmd:
   './node_modules/.bin/typedoc --theme markdown --platform gitbook --ignoreCompilerErrors --excludePrivate --excludeProtected --excludeExternals --excludeNotExported --target ES5 --module commonjs --hideGenerator --out ../../docs/browser-bindings/browser src',
  stdout:
   'Error: Unknown option: --platform\nError: Unknown option: --platform\n',
  stderr: '' }

Crashes when there are no generated reference docs

Overview

Not all versions of TypeDoc will not generate reference docs for packages that do not have any exports. Similarly, TypeDoc will not generate docs for packages that only export objects that TypeDoc does not document.

A good example of this behavior is that @0x/ts-doc-gen fails to generate reference documentation for the @0x/mesh-browser package. This occurs because the @0x/mesh-browser package only exports functions, which are not included in reference documentation in TypeDoc v0.15.0.

Expected Behavior

Generates minimal reference documentation or none at all.

Actual Behavior

Crashes with the following logs:

$ ts-doc-gen --sourceDir=./src --output=${npm_package_config_docsPath}
(node:77863) UnhandledPromiseRejectionWarning: Error: ENOENT: no such file or directory, open '../../docs/browser-bindings/browser/reference.md'
    at Object.openSync (fs.js:448:3)
    at Object.readFileSync (fs.js:348:35)
    at Object.<anonymous> (/Users/alextowle/0x-mesh/node_modules/@0x/ts-doc-gen/lib/src/index.js:173:31)
    at step (/Users/alextowle/0x-mesh/node_modules/@0x/ts-doc-gen/lib/src/index.js:32:23)
    at Object.next (/Users/alextowle/0x-mesh/node_modules/@0x/ts-doc-gen/lib/src/index.js:13:53)
    at fulfilled (/Users/alextowle/0x-mesh/node_modules/@0x/ts-doc-gen/lib/src/index.js:4:58)
(node:77863) UnhandledPromiseRejectionWarning: Unhandled promise rejection. This error originated either by throwing inside of an async function without a catch block, or by rejecting a promise which was not handled with .catch(). (rejection id: 1)
(node:77863) [DEP0018] DeprecationWarning: Unhandled promise rejections are deprecated. In the future, promise rejections that are not handled will terminate the Node.js process with a non-zero exit code.