Typedoc generation fails for pulumi/pulumi repo

[lindydonna]

A few findings:

1. Only typedoc version 0.8 seems to work for the pulumi-aws and pulumi-cloud. Any later version (0.9, 0.10, 0.11) will fail with hundreds of errors. I've added the typedoc install step in Clean up unused package.json and update Makefile #100
2. pulumi/pulumi fails to typedoc generate with the error below, on all versions of typedoc past 0.8. There is a file version.ts, so I'm not sure what it's failing on.

running typedoc on pulumi
~/go/src/github.com/pulumi/docs ~/go/src/github.com/pulumi/docs
fs.js:1000
  binding.stat(pathModule._makeLong(path), statValues);
          ^

Error: ENOENT: no such file or directory, stat '/Users/donnam/go/src/github.com/pulumi/pulumi/sdk/nodejs/version'
    at Error (native)
    at Object.fs.statSync (fs.js:1000:11)
    at /usr/local/lib/node_modules/typedoc/dist/lib/application.js:140:20
    at Array.forEach (native)
    at CliApplication.Application.expandInputFiles (/usr/local/lib/node_modules/typedoc/dist/lib/application.js:138:20)
    at CliApplication.bootstrap (/usr/local/lib/node_modules/typedoc/dist/lib/cli.js:58:28)
    at CliApplication.Application (/usr/local/lib/node_modules/typedoc/dist/lib/application.js:39:15)
    at new CliApplication (/usr/local/lib/node_modules/typedoc/dist/lib/cli.js:35:42)
    at Object.<anonymous> (/usr/local/lib/node_modules/typedoc/bin/typedoc:4:1)
    at Module._compile (module.js:570:32)
make: *** [generate] Error 1

[joeduffy]

@lindydonna Assigning it to you just until you find an owner.

[lukehoban]

The PR in pulumi/pulumi#1001 fixes the immediate problem you hit.

After that - I then saw this:

Using TypeScript 2.4.1 from /usr/local/lib/node_modules/typedoc/node_modules/typescript/lib
Error: /Users/luke/go/src/github.com/pulumi/pulumi/sdk/nodejs/cmd/run/index.ts(88)
 '(' expected.
make: *** [generate] Error 4

I can't tell what problem it's seeing - that line of code looks totally reasonable to me.

But if I force TypeDoc to use a later version of the TypeScreipt compiler, it completes succesfully.

Unfortunately, to do that, I had to delete node_modules/typedoc/node_modules/typescript and yarn add typescript@2.6.2 (or just put the latter in the package.json and yarn install).

I think officially TypeDoc versions it's dependency on TypeScript very rigidly - see TypeStrong/typedoc#624 (comment).

Anyhow, after those steps, make generate succeeds for me.

[lindydonna]

@lukehoban Thanks! It sounds like you're using node_modules installed in the docs repo? I started down that path, but got stuck because the script run_typedoc.sh cd's to each other repo (e.g. https://github.com/pulumi/docs/blob/master/scripts/run_typedoc.sh#L17). I should probably close #100, and instead change the script so that it runs typedoc from the root of the docs repo, pointing to each other pack folder. Does that seem like a good approach?

[lukehoban]

Not sure I quite follow. In my own setup, I'm picking up a globally installed typedoc. Not sure how we set this up on the docs deployment VMs, but I assume either way there's one single copy of typedoc somehwere that gets used across all the different packages we are generating docs for.

If the end goal is just to run this on the docs VM, I can take care of doing that - let's sync in person on what's needed.