How to use dgeni to parse documentation comments in typescript files

user_510711 0
Viewed 684

We have setup dgeni to extract markdown documentation out of our existing javascript files. I am trying to extend it to parse typescript files, too.

I thought just adding .ts files to the sourceFiles include would solve the problem, but it raises some errors: 

error:   Error processing docs:  Error: No file reader found for javascript/components/main.ts
  at matchFileReader (node_modules\dgeni-packages\base\processors\read-files.js:130:25)
  at node_modules\dgeni-packages\base\processors\read-files.js:66:99
  at <anonymous>

I found some commits like dgeni-packages:3e07adee84b7a795a0fb02d7181effa593fb9b4f and I am again searching and searching how to setup dgeni.

We generate our documentation with:

'use strict';

const path = require('canonical-path');
const {Dgeni, Package} = require('dgeni');

const docs= new Package('docs', [
  require('dgeni-markdown')
])
  .processor(require('./indexPage'))
  .config(function (log, readFilesProcessor, writeFilesProcessor, templateFinder, apiPagesProcessor) {
    log.level = 'warn';
    readFilesProcessor.basePath = path.resolve(__dirname, '..');
    readFilesProcessor.sourceFiles = [
      {
        include: 'src/main/javascript/**/*.js',
        basePath: 'src/main/javascript'
      },
    ];
    templateFinder.templateFolders.unshift(path.resolve(__dirname, 'templates'));
    apiPagesProcessor.pathFromOutputToRootFolder = '../..';
    writeFilesProcessor.outputFolder = 'docs/generated';
  });
const dgeni = new Dgeni([docs]);

module.exports = () => dgeni.generate().then(done);

dgeni.generate().then(done);

function done() {
  console.log('Generated documentation.');
}

Is there a easy way to get dgeni to parse typescript files, too? Just for comments like:

/**
 * @ngdoc directive
 * @module we.components
 * @name contactSlideout
 * @restrict E
 *
 * @description
 * Contact Slideout.
 *
 */
angularjs typescript javascript
2 Answers

For anyone coming here in 2019 or later, dgeni has changed a bit since the accepted answer. dgeni-markdown doesn't exist anymore. Here is how I got dgeni to parse Typescript correctly:

import { Categorizer } from "../processors/categorizer";
import * as path from 'path';
import { Package } from "dgeni";

const jsdocPackage = require('dgeni-packages/jsdoc');
const nunjucksPackage = require('dgeni-packages/nunjucks');
const typescriptPackage = require('dgeni-packages/typescript');

export let checkoutDocs =  new Package('checkout', [
  jsdocPackage,
  nunjucksPackage,
  typescriptPackage
]);

// This processor organizes what the typescriptPackage has tagged into objects that can be easily read by our templates.
checkoutDocs.processor(new Categorizer());

// Configure our dgeni-example package. We can ask the Dgeni dependency injector
// to provide us with access to services and processors that we wish to configure
checkoutDocs.config(function(readFilesProcessor, log, writeFilesProcessor, templateFinder, readTypeScriptModules, templateEngine) {

  // Set logging level
  log.level = 'info';

  // The typescriptPackage only uses the "readTypeScriptModules" processor, so disable readFilesProcessor.
  readFilesProcessor.$enabled = false;

  // Specify the base path used when resolving relative paths to source and output files
  readTypeScriptModules.basePath = path.resolve(__dirname, '../..');

  // Specify collections of source files that should contain the documentation to extract
  readTypeScriptModules.sourceFiles = [
    {
      // Process a single file for now
      include: 'src/billing/containers/billing.component.ts',
      basePath: 'src'
    }
  ];

  // Nunjucks and Angular conflict in their template bindings so change Nunjucks
  templateEngine.config.tags = {
    variableStart: '{$',
    variableEnd: '$}',
  };

  // Add a folder to search for our own templates to use when rendering docs
  templateFinder.templateFolders.unshift(path.resolve('./docs/templates'));

  // Specify how to match docs to templates.
  templateFinder.templatePatterns.unshift('common.template.html');

  // Specify where the writeFilesProcessor will write our generated doc files
  writeFilesProcessor.outputFolder  = path.resolve('./docs/build');
});

Also, the comments shouldn't always be directly above the export as the accepted answer states. I found that in Angular, a comment for a Component would only be picked up if it was above the @Component:

/**
 * Billing Container description to be picked up by dgeni.
 */
@Component({
  selector: '[billing-container]',
  template: '<ng-content></ng-content>',
  exportAs: 'BillingContainer'
})
export class BillingContainer {
}

The Angular Material repo is a good place to see Typescript and dgeni in action together if you're looking for more.

user_49760530
Related