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)](http://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 | [![Greenkeeper Enabled](https://badges.greenkeeper.io/TypeStrong/typedoc.svg)](https://greenkeeper.io/)
|
9 |
|
10 | ## Installation
|
11 |
|
12 | TypeDoc runs on Node.js and is available as an NPM package. You can install TypeDoc
|
13 | in your project's directory as usual:
|
14 |
|
15 | ```bash
|
16 | $ npm install typedoc --save-dev
|
17 | ```
|
18 |
|
19 | Like the TypeScript compiler, TypeDoc comes with a binary that can be called from anywhere
|
20 | if you install TypeDoc as a global module. The name of the executable is ``typedoc``.
|
21 |
|
22 | ```bash
|
23 | $ npm install typedoc --global
|
24 | $ typedoc
|
25 | ```
|
26 |
|
27 | ## Usage
|
28 |
|
29 | ### Shell
|
30 |
|
31 | TypeDoc accepts most of the command line arguments that the TypeScript compiler accepts. One major
|
32 | difference is the fact that one may pass an entire directory instead of individual files to the documentation
|
33 | generator. So in order to create a documentation for an entire project you simply type:
|
34 |
|
35 | ```bash
|
36 | $ typedoc --out path/to/documentation/ path/to/typescript/project/
|
37 | ```
|
38 |
|
39 | ### Important note
|
40 |
|
41 | Starting with version 0.2, TypeDoc no longer can predict whether files should be treated as modules
|
42 | or whether the project should be compiled into one big namespace. You must specify the `mode` argument
|
43 | in order to change the behaviour of TypeDoc.
|
44 |
|
45 |
|
46 | ### 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 | * `--json <path/to/output.json>`<br>
|
53 | Specifies the location and file name a json file describing the project is written to. When specified no documentation will be generated.
|
54 |
|
55 | #### Source file handling
|
56 | * `--exclude <pattern>`<br>
|
57 | Exclude files by the given pattern when a path is provided as source
|
58 | * `--includeDeclarations`<br>
|
59 | Turn on parsing of .d.ts declaration files.
|
60 | * `--externalPattern <pattern>`<br>
|
61 | Define a pattern for files that should be considered being external.
|
62 | * `--excludeExternals`<br>
|
63 | Prevent externally resolved TypeScript files from being documented.
|
64 | * `--excludePrivate`<br>
|
65 | Prevent private members from being included in the generated documentation.
|
66 |
|
67 | #### TypeScript compiler
|
68 | * `--module <commonjs, amd, system or umd>`<br>
|
69 | Specify module code generation: "commonjs", "amd", "system" or "umd".
|
70 | * `--target <ES3, ES5, or ES6>`<br>
|
71 | Specify ECMAScript target version: "ES3" (default), "ES5" or "ES6"
|
72 |
|
73 | #### Theming
|
74 | * `--theme <default|minimal|path/to/theme>`<br>
|
75 | Specify the path to the theme that should be used.
|
76 | * `--name <Documentation title>`<br>
|
77 | Set the name of the project that will be used in the header of the template.
|
78 | * `--readme <path/to/readme|none>`<br>
|
79 | Path to the readme file that should be displayed on the index page. Pass `none` to disable the index page
|
80 | and start the documentation on the globals page.
|
81 | * `--hideGenerator`<br>
|
82 | Do not print the TypeDoc link at the end of the page.
|
83 | * `--gaID`<br>
|
84 | Set the Google Analytics tracking ID and activate tracking code.
|
85 | * `--gaSite <site>`<br>
|
86 | Set the site name for Google Analytics. Defaults to `auto`
|
87 | * `--entryPoint <fully.qualified.name>`<br>
|
88 | Specifies the fully qualified name of the root symbol. Defaults to global namespace.
|
89 | * `--gitRevision <revision|branch>`<br>
|
90 | Use specified revision or branch instead of the last revision for linking to GitHub source files.
|
91 |
|
92 | #### Content
|
93 | * `--includes <path/to/includes>`<br>
|
94 | Specifies the location to look for included documents. One may use <code>[[include:FILENAME]]</code>
|
95 | in comments to include documents from this location.
|
96 |
|
97 | * `--media <path/to/media>`<br>
|
98 | Specifies the location with media files that should be copied to the output directory. In order to create
|
99 | a link to media files use the pattern <code>media://FILENAME</code> in comments.
|
100 |
|
101 | #### Miscellaneous
|
102 | * `--version`<br>
|
103 | Display the version number of TypeDoc.
|
104 | * `--help`<br>
|
105 | Display a simple cheat sheet.
|
106 |
|
107 | ### Webpack
|
108 |
|
109 | There is a plugin available to run TypeDoc with Webpack created by Microsoft. You can find it on NPM:<br>
|
110 | [https://www.npmjs.com/package/typedoc-webpack-plugin](https://www.npmjs.com/package/typedoc-webpack-plugin)
|
111 |
|
112 |
|
113 | ### Gulp
|
114 |
|
115 | There is a plugin available to run TypeDoc with Gulp created by Rogier Schouten. You can find it on NPM:<br>
|
116 | [https://www.npmjs.org/package/gulp-typedoc/](https://www.npmjs.org/package/gulp-typedoc/)
|
117 |
|
118 |
|
119 | ### Grunt
|
120 |
|
121 | There is a plugin available to run TypeDoc with Grunt created by Bart van der Schoor. You can find it on NPM:<br>
|
122 | [https://www.npmjs.org/package/grunt-typedoc](https://www.npmjs.org/package/grunt-typedoc)
|
123 |
|
124 | ## Plugins
|
125 |
|
126 | * [External Module Name](https://github.com/christopherthielen/typedoc-plugin-external-module-name) - Set the name of TypeDoc external modules
|
127 | * [Sourcefile URL](https://github.com/gdelmas/typedoc-plugin-sourcefile-url) - Set custom source file URL links
|
128 |
|
129 | ## Advanced guides and docs
|
130 |
|
131 | Visit our homepage for advanced guides and an extensive API documentation:<br>
|
132 | [http://typedoc.org](http://typedoc.org)
|
133 |
|
134 |
|
135 | ## Contributing
|
136 |
|
137 | Contributions are welcome and appreciated. You can find TypeDoc on GitHub, feel free to start
|
138 | an issue or create a pull requests:<br>
|
139 | [https://github.com/TypeStrong/typedoc](https://github.com/TypeStrong/typedoc)
|
140 |
|
141 |
|
142 | ## License
|
143 |
|
144 | Copyright (c) 2015 [Sebastian Lenz](http://typedoc.org).<br>
|
145 | Copyright (c) 2016-2017 [TypeDoc Contributors](https://github.com/TypeStrong/typedoc/graphs/contributors).<br>
|
146 | Licensed under the Apache License 2.0.
|