1 | # TypeDoc
|
2 |
|
3 | > Documentation generator for TypeScript projects.
|
4 |
|
5 | [![Build Status](https://travis-ci.org/TypeStrong/typedoc.svg?branch=master)](https://travis-ci.org/TypeStrong/typedoc)
|
6 | [![NPM Version](https://badge.fury.io/js/typedoc.svg)](https://badge.fury.io/js/typedoc)
|
7 | [![Chat on Gitter](https://badges.gitter.im/TypeStrong/typedoc.svg)](https://gitter.im/TypeStrong/typedoc?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
|
8 |
|
9 | ## Installation
|
10 |
|
11 | TypeDoc runs on Node.js and is available as an NPM package. You can install TypeDoc
|
12 | in your project's directory as usual:
|
13 |
|
14 | ```bash
|
15 | $ npm install typedoc --save-dev
|
16 | ```
|
17 |
|
18 | Like the TypeScript compiler, TypeDoc comes with a binary that can be called from anywhere
|
19 | if you install TypeDoc as a global module. The name of the executable is ``typedoc``.
|
20 |
|
21 | ```bash
|
22 | $ npm install typedoc --global
|
23 | $ typedoc
|
24 | ```
|
25 |
|
26 | ## Usage
|
27 |
|
28 | ### Shell
|
29 |
|
30 | TypeDoc accepts most of the command line arguments that the TypeScript compiler accepts. One major
|
31 | difference is the fact that one may pass an entire directory instead of individual files to the documentation
|
32 | generator. So in order to create a documentation for an entire project you simply type:
|
33 |
|
34 | ```bash
|
35 | $ typedoc --out path/to/documentation/ path/to/typescript/project/
|
36 | ```
|
37 |
|
38 | ### Important note
|
39 |
|
40 | Starting with version 0.2, TypeDoc no longer can predict whether files should be treated as modules
|
41 | or whether the project should be compiled into one big namespace. You must specify the `mode` argument
|
42 | in order to change the behaviour of TypeDoc.
|
43 |
|
44 | ### Arguments
|
45 |
|
46 | For a complete list of the command line arguments run `typedoc --help` or read [here](https://typedoc.org/guides/arguments/).
|
47 |
|
48 | * `--out <path/to/documentation/>`<br>
|
49 | Specifies the location the documentation should be written to.
|
50 | * `--mode <file|modules>`<br>
|
51 | Specifies the output mode the project is used to be compiled with.
|
52 | * `--options`<br>
|
53 | Specify a js option file that should be loaded. If not specified TypeDoc will look for 'typedoc.js' in the current directory.
|
54 | * `--json <path/to/output.json>`<br>
|
55 | Specifies the location and file name a json file describing the project is written to. When specified no documentation will be generated.
|
56 | * `--ignoreCompilerErrors`<br>
|
57 | Should TypeDoc still generate documentation pages even after the compiler has returned errors?
|
58 |
|
59 | #### Source file handling
|
60 | * `--exclude <pattern>`<br>
|
61 | Exclude files by the given pattern when a path is provided as source. Supports standard minimatch patterns (see [#170](https://github.com/TypeStrong/typedoc/issues/170))
|
62 | * `--includeDeclarations`<br>
|
63 | Turn on parsing of .d.ts declaration files.
|
64 | * `--externalPattern <pattern>`<br>
|
65 | Define a pattern for files that should be considered being external.
|
66 | * `--excludeExternals`<br>
|
67 | Prevent externally resolved TypeScript files from being documented.
|
68 | * `--excludeNotExported`<br>
|
69 | Prevent symbols that are not exported from being documented.
|
70 | * `--excludePrivate`<br>
|
71 | Prevent private members from being included in the generated documentation.
|
72 | * `--excludeProtected`<br>
|
73 | Prevent protected members from being included in the generated documentation.
|
74 |
|
75 | #### TypeScript compiler
|
76 | * `--module <commonjs, amd, system or umd>`<br>
|
77 | Specify module code generation: "commonjs", "amd", "system" or "umd".
|
78 | * `--target <ES3, ES5, or ES6>`<br>
|
79 | Specify ECMAScript target version: "ES3" (default), "ES5" or "ES6"
|
80 | * `--tsconfig <path/to/tsconfig.json>`<br>
|
81 | Specify a typescript config file that should be loaded. If not specified TypeDoc will look for 'tsconfig.json' in the current directory.
|
82 |
|
83 | #### Theming
|
84 | * `--theme <default|minimal|path/to/theme>`<br>
|
85 | Specify the path to the theme that should be used.
|
86 | * `--name <Documentation title>`<br>
|
87 | Set the name of the project that will be used in the header of the template.
|
88 | * `--readme <path/to/readme|none>`<br>
|
89 | Path to the readme file that should be displayed on the index page. Pass `none` to disable the index page
|
90 | and start the documentation on the globals page.
|
91 | * `--plugin`<br>
|
92 | Specify the npm plugins that should be loaded. Omit to load all installed plugins, set to 'none' to load no plugins.
|
93 | * `--hideGenerator`<br>
|
94 | Do not print the TypeDoc link at the end of the page.
|
95 | * `--gaID`<br>
|
96 | Set the Google Analytics tracking ID and activate tracking code.
|
97 | * `--gaSite <site>`<br>
|
98 | Set the site name for Google Analytics. Defaults to `auto`
|
99 | * `--entryPoint <fully.qualified.name>`<br>
|
100 | Specifies the fully qualified name of the root symbol. Defaults to global namespace.
|
101 | * `--gitRevision <revision|branch>`<br>
|
102 | Use specified revision or branch instead of the last revision for linking to GitHub source files.
|
103 |
|
104 | #### Content
|
105 | * `--includes <path/to/includes>`<br>
|
106 | Specifies the location to look for included documents. One may use <code>[[include:FILENAME]]</code>
|
107 | in comments to include documents from this location.
|
108 |
|
109 | * `--media <path/to/media>`<br>
|
110 | Specifies the location with media files that should be copied to the output directory. In order to create
|
111 | a link to media files use the pattern <code>media://FILENAME</code> in comments.
|
112 |
|
113 | #### Miscellaneous
|
114 | * `--version`<br>
|
115 | Display the version number of TypeDoc.
|
116 | * `--help`<br>
|
117 | Display all TypeDoc options.
|
118 |
|
119 | ### Webpack
|
120 |
|
121 | There is a plugin available to run TypeDoc with Webpack created by Microsoft. You can find it on NPM:<br>
|
122 | [https://www.npmjs.com/package/typedoc-webpack-plugin](https://www.npmjs.com/package/typedoc-webpack-plugin)
|
123 |
|
124 |
|
125 | ### Gulp
|
126 |
|
127 | There is a plugin available to run TypeDoc with Gulp created by Rogier Schouten. You can find it on NPM:<br>
|
128 | [https://www.npmjs.com/package/gulp-typedoc/](https://www.npmjs.com/package/gulp-typedoc/)
|
129 |
|
130 |
|
131 | ### Grunt
|
132 |
|
133 | There is a plugin available to run TypeDoc with Grunt created by Bart van der Schoor. You can find it on NPM:<br>
|
134 | [https://www.npmjs.com/package/grunt-typedoc](https://www.npmjs.com/package/grunt-typedoc)
|
135 |
|
136 | ## Plugins
|
137 |
|
138 | * [External Module Name](https://github.com/christopherthielen/typedoc-plugin-external-module-name) - Set the name of TypeDoc external modules
|
139 | * [Sourcefile URL](https://github.com/gdelmas/typedoc-plugin-sourcefile-url) - Set custom source file URL links
|
140 | * [Internal/External Module](https://github.com/christopherthielen/typedoc-plugin-internal-external) - Explicitly mark modules as `@internal` or `@external`
|
141 | * [Single Line Tags](https://github.com/christopherthielen/typedoc-plugin-single-line-tags) - Process certain `@tags` as single lines
|
142 | * [Localization](https://github.com/IgniteUI/typedoc-plugin-localization) - Generate documentation for different languages
|
143 |
|
144 | A list of all published Typedoc plugins can be found on NPM:<br>
|
145 | [https://www.npmjs.com/search?q=keywords:typedocplugin](https://www.npmjs.com/search?q=keywords:typedocplugin)
|
146 |
|
147 | ## Advanced guides and docs
|
148 |
|
149 | Visit our homepage for advanced guides and an extensive API documentation:<br>
|
150 | [https://typedoc.org](https://typedoc.org)
|
151 |
|
152 |
|
153 | ## Contributing
|
154 |
|
155 | This project is maintained by a community of developers. Contributions are welcome and appreciated.
|
156 | You can find TypeDoc on GitHub; feel free to start an issue or create a pull requests:<br>
|
157 | [https://github.com/TypeStrong/typedoc](https://github.com/TypeStrong/typedoc)
|
158 |
|
159 | For more information, read the [contribution guide](https://github.com/TypeStrong/typedoc/blob/master/CONTRIBUTING.md).
|
160 |
|
161 |
|
162 | ## License
|
163 |
|
164 | Copyright (c) 2015 [Sebastian Lenz](https://typedoc.org).<br>
|
165 | Copyright (c) 2016-2018 [TypeDoc Contributors](https://github.com/TypeStrong/typedoc/graphs/contributors).<br>
|
166 | Licensed under the Apache License 2.0.
|