microsoft / typedoc-webpack-plugin Goto Github PK

View Code? Open in Web Editor NEW

65.0 5.0 31.0 19 KB

This is a plugin for the Webpack build system that will run Typedoc in order to generate API documentation.

JavaScript 100.00%

typedoc-webpack-plugin's Introduction

Typedoc-Webpack-Plugin

This is a plugin for the Webpack build system that will run Typedoc in order to generate API documentation.

Installation

Run the following command inside your project directory to install:

npm install typedoc-webpack-plugin --save-dev

Note: Typedoc is required as peer dependency.

To install Typedoc, run the following command inside your project directory:

npm install typedoc --save-dev

Usage

To use, add a require for the module to the Webpack Configuration file, and then place into the plugin section:

var TypedocWebpackPlugin = require('typedoc-webpack-plugin');

...

plugins: [
	new TypedocWebpackPlugin({})
]

The options for the plugin mirror the options that are passed to typedoc. Refer to https://github.com/TypeStrong/typedoc for full options.

The default options that are set by the plugin are:

{
	out: './docs',
	module: 'commonjs',
	target: 'es5',
	exclude: '**/node_modules/**/*.*',
	experimentalDecorators: true,
	excludeExternals: true
}

Here is an example of a more expanded configuration:

plugins: [
	new TypedocWebpackPlugin({
		name: 'Contoso',
		mode: 'file',
		theme: './typedoc-theme/',
		includeDeclarations: false,
		ignoreCompilerErrors: true,
	})
]

You can pass either absolute or relative paths as the configuration parameter out. The default output path of the docs is relative to the output path specified in the webpack configuration. For example:

output: {
	path: './target/',
}

With the default configuration, the above example would produce the docs under the following path: ./target/docs.

Relative paths can also be specified as the out parameter. For example out: '../docs', would produce the docs under the following path: ./docs.

Output to a json file is also supported by setting the 'json' property instead of the 'out' property in your configuration. For example:

plugins: [
	new TypedocWebpackPlugin({
		name: 'Contoso',
		mode: 'file',
		json: './docs.json'
	})
]

Input

Specifying input for the plugin can be done in multiple ways

Single file or directory:

new TypedocWebpackPlugin({}, './src')

Array of files or directories:

new TypedocWebpackPlugin({}, ['./src', './other'])

Or this parameter can be left blank, in which case all .ts files in project root directory will be used as input

new TypedocWebpackPlugin({})

typedoc-webpack-plugin's People

Contributors

Stargazers

Watchers

typedoc-webpack-plugin's Issues

Allow to specify the project folder like on the actual cli

At the moment the expandInputFiles function have this value hard coded:

['./']

I think it is necessary to allow the user to pass in a custom array or string to modify the value..

A proposal would be changing the constructor to:

function TypedocWebpackPlugin(options, input) {
   this.inputFiles = ['./'];
   if (input) {
      this.inputFiles = (input.constructor === Array) ? input : [input];
   }
   ...

This repo is missing a LICENSE file

This repository is currently missing a LICENSE file.

A license helps users understand how to use your project in a compliant manner. You can find the standard MIT license Microsoft uses at: https://github.com/microsoft/repo-templates/blob/main/shared/LICENSE.

If you would like to learn more about open source licenses, please visit the document at https://aka.ms/license (Microsoft-internal guidance).

Problems after configuration in webpack

after configure typedoc webpack plugin build failed with error:

'Promise' only refers to a type, but is being used as a value here. Do you need to change your target library? Try changing the `lib` compiler option to es2015 or later.

tsconfig:

{
  "compileOnSave": false,
  "compilerOptions": {
    "module": "commonjs",
    "noImplicitAny": false,
    "noEmitOnError": true,
    "removeComments": false,
    "sourceMap": true,
    "target": "es5",
    "lib": [
      "es5",
      "dom",
      "es2015.promise",
      "es2015.symbol"
    ]
  },
  "exclude": [
    "node_modules",
    "wwwroot"
  ]
}

Rationale for using typedoc with WebPack rather than as standalone?

I was thinking it might be nice to explain the pros/cons of using TypeDoc through WebPack rather than as standalone?

I assume that its mostly so the documentation can be generated at the same time -- sort of a consolidation thing?

Please correct me if I'm wrong, but keeping a separate TSDoc script that is run less frequently (maybe pre-commit or once per PR) would be nicer in some situations for build times, KISS, etc...?

Oh... and thank you M$ (and other contributors) for all the dope tools!!!

using Typedoc plugins through Typedoc-Webpack-Plugin

Some time ago i am tried use typedoc-webpack-plugin like this:

  var typeDocPlugin = new TypedocWebpackPlugin(
            {
               mdPagesSourcePath: './backend/test-page',
              /// other settings            
            }
        );

where mdPagesSourcePath is param from typedoc-plugin-markdown
this config works with direct configuration for webpack-plugin.

But in this scenario throw error:
and get this error:
Error: Failed to get page collection. Error: Failed to get pages source path from options. Error: Pages source path must be specified.

I think this is because TypedocWebpackPlugin not pass unknown parameters to other plugins

Unable to exclude node_modules

Hi,

When using typedoc-webpack-plugin, the document is being generated,but it outputs errors from node_modules. I tried to override exclude,but no use.Is there any way to tell the plugin to avoid looking into node_modules folder?

Structure of project

Typedoc-webpack-plugin options in webpack.local.js


        new TypedocWebpackPlugin({
            name: "Test",
            module: "commonjs",
            out: "../../docs/ts",
            includeDeclarations: true,
            ignoreCompilerErrors: true,
            excludeExternals: true,
            moduleResolution: "node",
            theme: "minimal",
            excludePrivate: true
        })

Provide some information for installation and setup in the readme

Typedoc 0.5.0

The peer dependency to typedoc 0.4.4 is out dated

out directory relative paths should be resolved from webpack output.path

given:

var TypedocPlugin = require('typedoc-webpack-plugin');
{
  output: { path: __dirname + '/target' }
  plugin: [
    new TypedocPlugin({ out: './docs' })
  ]
}

the result documentation should end up in: __dirname/target/docs

Peer dependency of typedoc 0.5.0 is outdated

See title.

DeprecationWarning: Tapable.plugin is deprecated. Use new API on `.hooks` instead

help me.
I find some ways in google,but it not work.

Allow JSON Output

I would like to use Typedoc to generate JSON output on the fly through Webpack.

typedoc 11.0+ breaks this plugin's use of options

We just bumped our version of typedoc and it appears that something has broken with options.

I discovered this by logging the options being used from this plugin (typedocOptions), and then logging the options that the theme can see in one of the helpers. It appears that only some of the options are being passed through.

From the plugin:

{ module: 'commonjs',
  target: 'es5',
  exclude: '**/node_modules/**/*.*',
  experimentalDecorators: true,
  excludeExternals: true,
  out: '../docs/api',
  readme: 'none',
  theme: 'markdown',
  name: 'Bitski.js',
  mode: 'modules',
  includeDeclarations: false,
  mdSourceRepo: 'https://github.com/BitskiCo/bitski-js-sdk',
  mdSourceBranch: 'master' }

From the helper:

{ exclude: [ '**/node_modules/**/*.*' ],
  excludeExternals: true,
  out: '<redacted>',
  readme: 'none',
  theme: 'markdown',
  name: 'Bitski.js',
  mode: 1,
  includeDeclarations: false }

mdSourceRepo and mdSourceBranch are used within another plugin we use, and are no longer being passed through.

It appears a number of things related to options changed with this PR, so I'm guessing that it's related.
TypeStrong/typedoc#610

In the meantime, using typedoc 10.0 works alright.

Please provide some method of specifying an absolute path

The relative path setup for the output from this plugin expects to be placed in the dist directory with the rest of the production minified files, however, with my setup I'm desiring this directory layout.

/build/dist - Production minified code
/build/typedoc - Typedoc output

The way this plugin is built forces any output into /build/dist, which for my continuous integration setup is undesirable. Setting out to '../typedoc' does not produce an output that is one level back in the directory tree.

This repo is missing important files

There are important files that Microsoft projects should all have that are not present in this repository. A pull request has been opened to add the missing file(s). When the pr is merged this issue will be closed automatically.

Microsoft teams can learn more about this effort and share feedback within the open source guidance available internally.

Merge this pull request

Tapable.plugin is deprecated

Use of .plugin is deprecated in webpack 4. Users of this plugin will now get the following errror:

DeprecationWarning: Tapable.plugin is deprecated. Use new API on `.hooks` instead

The current usage in this plugin is on index.js#64

remove lodash

Properties with multiple allowable types render incorrectly

Issue:

When a property has multiple allowable types, the asterisks that are supposed to italicize the property types have a space between the type and the asterisk. For example: * string | boolean *. When the markdown file is generated, this results in a stray asterisk before the types, and a stray bullet below.

Proposed solution:

When a property can have multiple types, the asterisks should be located immediately next to the types, with no space, like this: *string | boolean*.

The following sample interface would exhibit this behavior:

export interface ISettings {
  aSetting: string | boolean;
}

Which renders the following (broken) markdown:

## Properties

<a id="asetting"></a>

###  aSetting

**● aSetting**: * `boolean` &#124; `string`
*

*Defined in [path/to/file](https://path/to/github/file)*

See the following screenshot: