Typedoc: Basic example of using within node?

[topherfangio]

We are building a set of angular components in TypeScript, and I am attempting to integrate TypeDoc into our build system to automatically pull out the options for each component and generate some HTML so that it is more automated (we're currently copy/pasting).

I noticed that I can create a new instance of the typedoc.Application within node, but I am a bit lost as to where to go from here. I'm just printing out the app object, and it all happens so fast that I can't imagine it's actually doing anything.

Can you give me some pointers on how to get up-and-running and the types of things I might want to access/use?

I'd be happy to create a wiki page or update the README with my findings and some examples if you can point me down the right path :-)

Thanks!

/*
 * My current (VERY basic) code
 */
var gulp = require('gulp');
var typedoc = require('typedoc');

gulp.task('microsite:build', function(cb) {
  var app = new typedoc.Application({
    includes: ["components/**/*.ts"]
  });

  console.log(app);

  // TODO: Iterate over the components and extract some options

  // TODO: Generate a JSON file/object which we can use within Angular to generate HTML

  cb();
});

[sebastian-lenz]

Hi Topher, your setup seems to be okay. After requiring the TypeDoc module you can create an instance of the application class like above. You can pass an object to the constructor containing the desired options, a full list of available options is available here.

The application exposes the convert method which expects an array of source files and returns a ProjectReflection instance. This root reflection contains all reflections of the given source files and offers utility methods to work with them, see the docs for details. If you want to get the data TypeDoc stores using the --json option you may call the toObject of the project reflection.

Using the generateDocs method of the application you can directly generate a html documentation, the generateJson method writes a json file. Both methods require a list of source files or a ProjectReflection as their first argument and the desired output location as their second argument. You can find the full documentation of the application class here.

TypeDoc has no support for glob patterns, you must expand the pattern in your code. However, you may use the expandInputFiles method of the application to replace directories in your source array with the contained files.

TypeDoc has built in grunt support, the script is a good example of how to run TypeDoc programmatically. Check it out for a basic example.

[topherfangio]

Thanks Sebastian! I'll take a look at it and post back here if I can get it working :-)

[topherfangio]

After I upgraded to 0.3.4 (I was still on 0.2.3) I got it working and was able to extract the necessary information that I needed!

Thanks so much for your help!

Here's an excerpt of the semi-final solution for future reference (I still need it to iterate over every single TypeScript file and actually output the final JSON, but this is close):

var path = require('path');
var typedoc = require('typedoc');

gulp.task('docs:extract', function(cb) {
    // Setup our paths
    var outPath = path.join('build', 'test-file.json');
    var filePaths = [
        path.join('components', 'my-component.ts')
    ];

    // Setup our TypeDoc app
    var app = new typedoc.Application({
        name: 'My Awesome App'
    });

    // Actually generate the JSON file
    app.generateJson(filePaths, outPath);

    // Parse it
    var json = JSON.parse(fs.readFileSync(outPath, 'utf8'));

    // Clean up our JSON with a special function that removes unnecessary stuff
    var cleaned = cleanupJson(json);

    cb();
});

Hope this helps someone in the future!