UNPKG

3.83 kBMarkdownView Raw
1# JSDoc
2
3[![Build Status](https://travis-ci.org/jsdoc/jsdoc.svg?branch=master)](http://travis-ci.org/jsdoc/jsdoc)
4
5An API documentation generator for JavaScript.
6
7Want to contribute to JSDoc? Please read `CONTRIBUTING.md`.
8
9Installation and Usage
10----------------------
11
12JSDoc supports stable versions of Node.js 8.15.0 and later. You can install
13JSDoc globally or in your project's `node_modules` folder.
14
15To install the latest version on npm globally (might require `sudo`;
16[learn how to fix this](https://docs.npmjs.com/resolving-eacces-permissions-errors-when-installing-packages-globally)):
17
18 npm install -g jsdoc
19
20To install the latest version on npm locally and save it in your package's
21`package.json` file:
22
23 npm install --save-dev jsdoc
24
25**Note**: By default, npm adds your package using the caret operator in front of
26the version number (for example, `^3.5.2`). We recommend using the tilde
27operator instead (for example, `~3.5.2`), which limits updates to the most
28recent patch-level version. See
29[this Stack Overflow answer](https://stackoverflow.com/questions/22343224) for
30more information about the caret and tilde operators.
31
32To install the latest development version locally, without updating your
33project's `package.json` file:
34
35 npm install git+https://github.com/jsdoc/jsdoc.git
36
37If you installed JSDoc locally, the JSDoc command-line tool is available in
38`./node_modules/.bin`. To generate documentation for the file
39`yourJavaScriptFile.js`:
40
41 ./node_modules/.bin/jsdoc yourJavaScriptFile.js
42
43If you installed JSDoc globally, run the `jsdoc` command:
44
45 jsdoc yourJavaScriptFile.js
46
47By default, the generated documentation is saved in a directory named `out`. You
48can use the `--destination` (`-d`) option to specify another directory.
49
50Run `jsdoc --help` for a complete list of command-line options.
51
52## Templates and tools
53
54The JSDoc community has created templates and other tools to help you generate
55and customize your documentation. Here are a few of them:
56
57### Templates
58
59+ [jaguarjs-jsdoc](https://github.com/davidshimjs/jaguarjs-jsdoc)
60+ [DocStrap](https://github.com/docstrap/docstrap)
61([example](https://docstrap.github.io/docstrap))
62+ [jsdoc3Template](https://github.com/DBCDK/jsdoc3Template)
63 ([example](https://github.com/danyg/jsdoc3Template/wiki#wiki-screenshots))
64+ [minami](https://github.com/Nijikokun/minami)
65+ [docdash](https://github.com/clenemt/docdash)
66([example](http://clenemt.github.io/docdash/))
67+ [tui-jsdoc-template](https://github.com/nhnent/tui.jsdoc-template)
68([example](https://nhnent.github.io/tui.jsdoc-template/latest/))
69+ [better-docs](https://github.com/SoftwareBrothers/better-docs)
70([example](https://softwarebrothers.github.io/admin-bro-dev/index.html))
71
72### Build tools
73
74+ [JSDoc Grunt plugin](https://github.com/krampstudio/grunt-jsdoc)
75+ [JSDoc Gulp plugin](https://github.com/mlucool/gulp-jsdoc3)
76
77### Other tools
78
79+ [jsdoc-to-markdown](https://github.com/jsdoc2md/jsdoc-to-markdown)
80+ [Integrating GitBook with
81JSDoc](https://medium.com/@kevinast/integrate-gitbook-jsdoc-974be8df6fb3)
82
83## For more information
84
85+ Documentation is available at [jsdoc.app](https://jsdoc.app/).
86+ Contribute to the docs at
87[jsdoc/jsdoc.github.io](https://github.com/jsdoc/jsdoc.github.io).
88+ [Join JSDoc's Slack channel](https://jsdoc-slack.appspot.com/).
89+ Ask for help on the
90[JSDoc Users mailing list](http://groups.google.com/group/jsdoc-users).
91+ Post questions tagged `jsdoc` to
92[Stack Overflow](http://stackoverflow.com/questions/tagged/jsdoc).
93
94## License
95
96JSDoc 3 is copyright (c) 2011-present Michael Mathews <micmath@gmail.com> and
97the [contributors to JSDoc](https://github.com/jsdoc/jsdoc/graphs/contributors).
98
99JSDoc 3 is free software, licensed under the Apache License, Version 2.0. See
100the file `LICENSE.md` in this distribution for more details.