rogierschouten / gulp-typedoc Goto Github PK

Hi,

I am trying to get this plugin to work for my angular typescript project and have defined a gulp task like so:

gulp.task('typedoc', function() {
  return gulp
    .src(['./src/client/typings/**/*.d.ts',
        './src/client/app/**/*.module.ts',
        './src/client/app/**/*.run.ts',
        './src/client/app/**/*.config.ts',
        './src/client/app/**/*.enum.ts',
        './src/client/app/**/*.controller.ts',
        './src/client/app/**/*.model.ts',
        './src/client/app/**/*.directive.ts',
        './src/client/app/**/*.filter.ts',
        './src/client/app/**/*.service.ts',
        './src/client/app/interfaces/**/*.ts'])
    .pipe(plugins.typedoc({
      module: 'commonjs',
      target: 'es5',
      includeDeclarations: true,
      out: 'docs/',
      name: 'My project title',
      ignoreCompilerErrors: false,
      version: true
    }));
});

When I run the task I just get the following in the console:

[12:22:18] Starting 'typedoc'...
[12:22:20]
TypeDoc {{ VERSION }}
Using TypeScript 2.1.6 from C:\Users\rparker\Documents\GitHub\interact\node_modules\typedoc\node_modules\typescript\lib

Nothing gets output into my docs directory, and the task never completes.

I notice in the docs it says

The plugin takes an object, of which all properties are passed transparently to typedoc. Pipe in TypeScript files. The documentation files are not piped out.

Last sentence says the files are not piped out, is that correct? If so, how do I get the files for viewing?

Thanks

The type definitions are missing some of the keys accepted by Typedoc. For example, I get errors when setting tsconfig or ignoreCompilerErrors.
Since the options are mostly passed as-is to typedoc, it would be better if the options of this lib were derived from those of typedoc.

I trying to exclude some files for the gulp-typedoc tool and they are processed anyway.
Here is my gulp file:

var gulp = require('gulp');
var typedoc = require("gulp-typedoc");

gulp.task("doc", function()
{
return gulp.src(["app/*/.ts"])
.pipe(typedoc({

  // TypeScript options (see typescript docs) 
  module: "commonjs", 
  target: "es6",
  experimentalDecorators: true,

  // Output options (see typedoc docs) 
  out: "./Doc", 

  // TypeDoc options (see typedoc docs) 

  exclude: "**/*.spec.ts",
  // since the exclude tag is not working, I have put ignoreCompilerErrors to true to create the doc anyway.
  // ignoreCompilerErrors: true,

  name: "One MiniStar", 
  version: true

  })) ;

});

Is there a way to specify an option that doesn't take an argument? It seems that the code at https://github.com/rogierschouten/gulp-typedoc/blob/master/index.js#L19 always assumes there will be an argument to any option. Perhaps that line could be modified to only push the value if the value is non-null.

like gulp-tslint or add option we can use custom typedoc like gulp-typescript.

As you know, typedoc is updating to use typescript 1.8.10 by TypeStrong/typedoc#204.
Now, we should use sierrasoftworks/typedoc#v1.8.10 if we use typescript latest, and we should use sierrasoftworks/gulp-typedoc#v1.8.10.

However, I want to use original repo as possible, and there are some situations to use own custom typedoc with this plugin.

What about this suggestion?

Hi,
It is currently inconvenient to use this plugin from Typescript since it is not typed.

Could you provide type definitions? They can be written manually if you don't want to convert your package to Typescript.

I'm using gulp-typedoc 3.0.1. We run two gulp-typedoc on two different sets of files and for each set generate both json and doc output. What I've found is that when both tasks run (effectively in parallel), I only get output for one of the tasks. The output directory for the other is empty. I've found that if I either disable json output or set the typedoc cleanOutputDir=false setting, then I get output for both sets of files.

Looking at the code, I suspect it's because doc output is generated, then json is generated immediately afterwards, without using await for the doc output to complete:

if (out) app.generateDocs(project, out);  // TODO promisified!!
if (json) app.generateJson(project, json); // TODO promisified!!

In the typedoc cli code, this uses await:

const out = app.options.getValue("out");
if (out) {
    await app.generateDocs(project, out);
}
const json = app.options.getValue("json");
if (json) {
    await app.generateJson(project, json);
}

I believe running the generateJson while generateDocs is running causes some state to get confused inside of typedoc.

TypeDoc 0.24.0 removed the logger option used here:

https://github.com/rogierschouten/gulp-typedoc/blob/master/index.js#L37-L44

TypeDoc 0.25.0 made changes to bootstrap that appears to have broken this plugin:

TypeStrong/typedoc#2268

Is there a way to generate docs in presence of TypeScript errors?
Sometimes, even often, it is needed to make docs for your team, even when code has a few compile-time glitches.
Thank you for this work. Awesome and useful lib.

[email protected] depends on event-stream^3.3.4, so when users install gulp-typedoc, they'll get the highest version of v3. event-stream 3.3.5 through 3.3.6 depends on a package called "flatmap-stream", which was once on the npm registry, but it is no longer there.

So when users install gulp-typedoc, they'll get the following error:

npm ERR! No valid versions available for flatmap-stream

[email protected] doesn't depend on flatmap-stream, and neither does v4.0.0 or higher. Possible ways to fix this:

1. lock the dependency of "event-stream": "^3.3.4" to "event-stream": "3.3.4", or
2. update to "event-stream": "^4.0.0" (breaking change)

It would be cool if README has more content, examples etc.

For example there is no typescript option "includeDeclarations", I think there was no such thing in typescript (tsc or tsconfig) at all.

I'm using gulp-typedoc version 1.2.1 and receiving the below error:

[14:23:14] Using gulpfile ~\Documents\Visual Studio 2013\Projects\FlexViewWeb\FlexViewWeb\gulpfile.js
[14:23:14] Starting 'typedoc'...
undefined:1
{
^
SyntaxError: Unexpected token 
at Object.parse (native)
at PackagePlugin.onBeginResolve (C:\[truncated]\node_modules\gulp-typedoc\node_modules\typedoc\bin\typedoc.js:5334:48)
at Converter.EventDispatcher.dispatch (C:\[truncated]\node_modules\gulp-typedoc\node_modules\typedoc\bin\typedoc.js:102:34)
at Converter.resolve (C:\[truncated]\node_modules\gulp-typedoc\node_modules\typedoc\bin\typedoc.js:2048:22)
at Converter.convert (C:\[truncated]\node_modules\gulp-typedoc\node_modules\typedoc\bin\typedoc.js:2005:36)
at Application.convert (C:\[truncated]\node_modules\gulp-typedoc\node_modules\typedoc\bin\typedoc.js:430:41)
at Stream.<anonymous> (C:\[truncated]\node_modules\gulp-typedoc\index.js:54:22)
at _end (C:\[truncated]b\node_modules\gulp-typedoc\node_modules\event-stream\node_modules\through\index.js:65:9)
at Stream.stream.end (C:\[truncated]\node_modules\gulp-typedoc\node_modules\event-stream\node_modules\through\index.js:74:5)
at DestroyableTransform.onend (C:\[truncated]\node_modules\gulp\node_modules\vinyl-fs\node_modules\through2\node_modules\readable-stream\lib\_stream_readable.js:523:10
)

My gulp task looks like:

gulp.task("typedoc", function () {
return gulp
    .src(["Engineering/App/**/*.ts"])
    .pipe(typedoc({
        module: "commonjs",
        target: "es5",
        out: "docs/",
        name: "FlexView Web"
    }))
;

});

To my knowledge, there aren't any strange characters in my Typescript files. Ideas?

hello,i use typedoc and gulp-typedoc order to get markdown file
when i run gulp without install npm plugin 'typedoc-plugin-markdown'
anythings is all right.
but when i run gulp with install npm plugin 'typedoc-plugin-markdown',
it was some error has happen
npm run gulpdoc

my gulpfile.js

my package.json

if i just run typedoc ,it was all right too

npm run typedoc

result like this ,it generate some *.md file

what shoud i to do,hope to get some help ,thanks

If you pass either a custom logger or the typedoc-accepted "none" value, gulp-doc will ignore it, create its own logger, and render the app version to the output.

That happens because it doesn't check for an options value before assigning it a new value:

// index.js (line 39)
// reduce console logging
options.logger = function(message, level, newline) {
    if (level === 3) {
        gutil.log(gutil.colors.red(message));
    }
}

I have a fix proposal at my fork: https://github.com/pjbatista/gulp-typedoc. Let me know what you think, Rogier.

Says the task finished but does not return to the command line.

It would be nice to allow this as an option:
TypeStrong/typedoc@c288c9b

By default, the plugin will output log messages from TypeDoc. Specify logger: 'none' to suppress TypeDoc logging altogether.

 var typedoc = require("gulp-typedoc");
  gulp.task("typedoc", function() {
return gulp
	.src(["data/*.ts"])
	.pipe(typedoc({
		// Output options (see TypeDoc docs http://typedoc.org/api/interfaces/typedocoptionmap.html)
		// NOTE: the out option and the json option cannot share the same directory
		out: "./out/html/",
		json: "/out/file.json",

		// TypeDoc options (see TypeDoc docs http://typedoc.org/api/interfaces/typedocoptionmap.html)
		name: "my-project",
		theme: "/path/to/my/theme",
		plugin: ["my", "plugins"],
		version: true,
                    logger: none
	}));
   });

Error:

I'd like to see an option for including the config settings from the tsconfig.json file that is present in many TypeScript projects. This would keep settings in sync and minimize discrepancy.

Thanks!

Is it possible to provide an option in the plugin to have it use a folder. spawning a child process is less than ideal.

Support the theme config option too.

Grunt plugin does this, should be possible too.

Here's the documentation for it: https://typedoc.org/guides/options/#includeversion

According to the typedoc 0.20.36 version I think the app.bootstrap should have an entryPoints option like below

app.bootstrap({
// typedoc options here
entryPoints: ["src/index.ts"],
});

const project = app.convert();

It should be possible to catch any errors thrown by gulp-typedoc:

gulp.src("./src")
.pipe(typedoc({
    module: "commonjs",
    target: "es6",
    ...
}))
.on("error", function() {
    this.emit("end");
});

Unfortunately, underlying typescript errors are not caught:

[10:12:20] Starting 'doc'...
[10:12:20] Starting 'typescript'...
events.js:141
	throw er; // Unhandled 'error' event

the ignoreCompilerErrors flag doesn't help in this case as the emit("end") is used to fail a normal build when we want to see typescript errors, but continue a gulp watch without crashing.

Hey there, in the docs, it doesn't use an ignore/exclude option.

Since ignoring node_modules is such a common task, it would be really convenient to document this.

This is what is in the readme:

var typedoc = require("gulp-typedoc");

gulp.task("typedoc", function() {
	return gulp
		.src(["data/*.ts"])
		.pipe(typedoc({
			// TypeScript options (see typescript docs)
			module: "commonjs",
			target: "es5",
			includeDeclarations: true,

			// Output options (see typedoc docs)
			out: "./out",
			json: "output/to/file.json",

			// TypeDoc options (see typedoc docs)
			name: "my-project",
			theme: "/path/to/my/theme",
			plugins: ["my", "plugins"],
			ignoreCompilerErrors: false,
			version: true,
		}));
});

I tried this and it seems to work (but I am not sure whether it's ignore or exclude that's actually doing the work:

gulp.task('typedoc', function() {
  return gulp
  .src([path.resolve(`${sumanRoot}/**/*.ts`)])
  .pipe(typedoc({
    module: 'commonjs',
    target: 'es5',
    ignore: '**/node_modules/**',           // <<<<<<<<<<<<<<<<
    exclude: '**/node_modules/**',        // <<<<<<<<<<<<<<< 
    out: 'typedocs/',
    ignoreCompilerErrors: true,
    version: true,
    name: 'The SumanJS Documentation'
  }));
});

Receive Unkown option: json When trying to configuring json: "path" in gulpfile.js

Older version of gulp-typedoc is working. But I want update it to latest. Now I have latest version of gulp-typedoc and typescipt. Facing many errors like below:

error TS2322: Type 'Timeout' is not assignable to type 'number | boolean'.
error TS2339: Property 'msSaveBlob' does not exist on type 'Navigator'.
error TS2345: Argument of type 'DataManager & Record<"result", unknown>' is not assignable to parameter of type 'string'.
error TS2440: Import declaration conflicts with local declaration of 'ColumnModel'.
error TS2365: Operator '>=' cannot be applied to types 'number' and 'string | number'.
error TS2532: Object is possibly 'undefined'.
error TS2300: Duplicate identifier 'Promise'.
error TS2403: Subsequent variable declarations must have the same type. Variable 'require' must be of type 'NodeRequire', but here has type 'Require'
error TS2440: Import declaration conflicts with local declaration of 'PluginConfig'.
error TS2307: Cannot find module '@angular/core' or its corresponding type declarations.

Question
This is my typedoc file:

'use strict';

// Node JS global scope
var gulp = global.gulp = global.gulp || require('gulp');
global.config = global.config || require('../utils/common.js');
var config = global.config.config();

gulp.task('typedoc', async function (done) {
var typedoc = require('gulp-typedoc');
gulp.src(config.typedoc)
.pipe(typedoc({

    // TypeScript options (see typescript docs) 
    module: 'amd',
    target: 'es5',
    moduleResolution: 'node',
    includeDeclarations: true,
    emitDecoratorMetadata: true,
    experimentalDecorators: true,


    // Output options (see typedoc docs) 
    out: './public/api',
    json: './public/api/file.json',

    // TypeDoc options (see typedoc docs) 
    name: 'Syncfusion TypeScript',
    ignoreCompilerErrors: true,
    version: true,
    theme: 'minimal',
    excludeExternals: true,
    excludeNotExported: true,
    stripInternal: true
}))
.on('end', function () {
    gulp.src('./readme/*.*')
        .pipe(gulp.dest('./public/api/readme'))
        .on('end', function () { done(); })
        .on('error', function (e) { done(e); });
})
.on('error', function (e) {
    done(e);
});

});

tsconfig file:

{
"compilerOptions": {
"target": "es5",
"module": "amd",
"declaration": true,
"removeComments": true,
"noLib": false,
"experimentalDecorators": true,
"sourceMap": true,
"pretty": true,
"allowUnreachableCode": false,
"allowUnusedLabels": false,
"noImplicitAny": true,
"noImplicitReturns": true,
"noImplicitUseStrict": false,
"noFallthroughCasesInSwitch": true,
"allowJs": false,
"forceConsistentCasingInFileNames": true,
"moduleResolution": "node",
"types": ["jasmine","jasmine-ajax","requirejs","chai","es6-promise"],
"suppressImplicitAnyIndexErrors": true
},
"exclude": [
"node_modules",
"dist",
"public",
"coverage",
"test-report",
"typings/browser.d.ts",
"typings/browser"
],
"compileOnSave": false
}

According to the typedoc 0.20.36 version, I think the app.bootstrap() should have an entryPoints option like below

app.bootstrap({
// typedoc options here
entryPoints: ["src/index.ts"],
});

Currently with the latest gulp-typedoc version and with the below code
this.gulp.src(["./source/**/*.ts"])
.pipe(typedoc({out: "typedoc/",
hideGenerator: true,
name: "test"}));

The output is not generated as expected. It just renders with empty HTML.

Currently in our project we are using TypeScript 1.5.3. The latest version is 1.6.0-beta.
typedoc v0.8 is using TS 1.5.3, and typedoc v0.9 and newer is using TS 1.6.0-beta.

Is it possible to specify which version of typedoc (or TypeScript) to use?
Can you add such config?

Thanks!
Kristiyan

Could you please have this plugin not execute if no files are passed to it? Right now it throws an error. It might sound like an odd request, but a lot of people use the gulp-newer plugin that passes all files through if and only if any of them have a modification time newer than the destination file.

This saves tons of time when you have your build broken down into a bunch of small tasks. Because each task only executes if its source files are newer than its output file. I would like to use it so the documentation is only rebuilt if any of the source files are newer than the documentation index.html file.

return gulp.src(SOURCE_FILES)
.pipe(newer(DOC_DIR + "index.html")
.pipe(typedoc(...));

It seems to be common practice to have this behavior as I'm using a 9 other gulp plugins and they don't perform any actions or throw any errors if they aren't feed any files.

Also, thanks for your hard work on the plugin. It is a great help.

Hello,
I'm sending an object reference to the gulp-typedoc constructor like so:

import typedoc from 'gulp-typedoc'

const options = {
  typedoc: {
    name: projectName,
    out: paths.dest.docs,
    theme: 'default',
    version: true,
  }
}

const docs = async () => {
  return src(`${paths.src.root}/engine/**/*.ts`)
    .pipe(typedoc(options.typedoc))
    .on('error', log.error)
}

This works fine on the first run, but fails on subsequent runs due to mutations to options.typedoc, which changes to this:

{
  name: projectName,
  theme: 'default',
  logger: [Function (anonymous)]
}

As a result, I get the following error message:

[PluginError: You must either specify the 'out' or 'json' option.] {
  plugin: 'gulp-typedoc',
  showProperties: true,
  showStack: false,
  __safety: { toString: [Function: bound ] }
}

Using Gulp to build my project, I'm trying to use gulp-typedoc to generate its documentation within a dedicated Gulp task.
As I need to perform additional actions on the docs after it got generated, I'm using Gulp's .on(), and I noticed the docs folder is not generated for a few instants after the task has ended:

function myGulpTask(done) {
    return gulp
        .src("src/**/*.ts")
        .pipe(gulpTypedoc({ out: "docs" }))
        .on("end", () => {
            console.log(fs.existsSync("docs")); // 'false'.

            setTimeout(() => {
                console.log(fs.existsSync("docs")); // 'true'.
            }, 1000);
        });
}

I suppose the right behaviour of the module should be to pass the TypeDoc's result into a pipe and let Gulp save it with gulp.dest("my/out/path"), like this:

function myGulpTask(done) {
    return gulp
        .src("src/**/*.ts")
        .pipe(gulpTypedoc())
        .pipe(gulp.dest("docs"))
        .on("end", () => {
            console.log(fs.existsSync("docs")); // 'true'.
        });
}

is there an option to suppress private properties?