UNPKG

4.35 kBMarkdownView Raw
1<p align="center">
2 <img src="./.github/documentation-js-logo.png" width="650" />
3</p>
4
5<p align="center">
6 The documentation system for modern JavaScript
7</p>
8
9[![Circle CI](https://circleci.com/gh/documentationjs/documentation/tree/master.svg?style=shield)](https://circleci.com/gh/documentationjs/documentation/tree/master)
10[![npm version](https://badge.fury.io/js/documentation.svg)](http://badge.fury.io/js/documentation)
11[![Gitter](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/documentationjs/documentation?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge)
12[![David](https://david-dm.org/documentationjs/documentation.svg)](https://david-dm.org/documentationjs/documentation)
13[![Inline docs](http://inch-ci.org/github/documentationjs/documentation.svg?branch=master&style=flat-square)](http://inch-ci.org/github/documentationjs/documentation)
14
15[:date: Current maintenance status](https://github.com/documentationjs/documentation/wiki/Current-maintenance-status)
16
17* Supports modern JavaScript: ES5, ES2017, JSX, Vue and [Flow](https://flow.org/) type annotations.
18* Infers parameters, types, membership, and more. Write less documentation: let the computer write it for you.
19* Integrates with GitHub to link directly from documentation to the code it refers to.
20* Customizable output: HTML, JSON, Markdown, and more
21
22## Examples
23
24- [HTML output with default template](https://documentation.js.org/html-example/)
25- [Markdown](https://github.com/documentationjs/documentation/blob/master/docs/NODE_API.md)
26- [JSON](https://documentation.js.org/html-example/index.json)
27
28## Documentation
29
30- [Getting Started](docs/GETTING_STARTED.md): start here
31- [Usage](docs/USAGE.md): how to use documentation.js
32- [Recipes](docs/RECIPES.md): tricks for writing effective JSDoc docs
33- [Node API](docs/NODE_API.md): documentation.js's self-generated documentation
34- [Configuring documentation.js](docs/CONFIG.md)
35- [FAQ](docs/FAQ.md)
36- [Troubleshooting](docs/TROUBLESHOOTING.md)
37- [Theming](docs/THEMING.md): tips for theming documentation output in HTML
38- [See also](https://github.com/documentationjs/documentation/wiki/See-also): a list of projects similar to documentation.js
39
40## User Guide
41
42Globally install `documentation` using the [npm](https://www.npmjs.com/) package manager:
43
44```sh
45$ npm install -g documentation
46```
47
48This installs a command called `documentation` in your path, that you can
49point at [JSDoc](http://usejsdoc.org/)-annotated source code to generate
50human-readable documentation. First, run `documentation` with the `--help`
51option for help:
52
53```sh
54Usage:
55
56# generate markdown docs for index.js and files it references
57documentation build index.js -f md
58
59# generate html docs for all files in src
60documentation build src/** -f html -o docs
61
62# document index.js, ignoring any files it requires or imports
63documentation build index.js -f md --shallow
64
65# build and serve HTML docs for app.js
66documentation serve app.js
67
68# build, serve, and live-update HTML docs for app.js
69documentation serve --watch app.js
70
71# validate JSDoc syntax in util.js
72documentation lint util.js
73
74# update the API section of README.md with docs from index.js
75documentation readme index.js --section=API
76
77# build docs for all values exported by index.js
78documentation build --document-exported index.js
79
80Commands:
81 serve [input..] generate, update, and display HTML documentation
82 build [input..] build documentation
83 lint [input..] check for common style and uniformity mistakes
84 readme [input..] inject documentation into your README.md
85
86Options:
87 --version Show version number [boolean]
88 --help Show help [boolean]
89```
90
91## [Contributing](CONTRIBUTING.md)
92
93_We have plenty of
94[issues](https://github.com/documentationjs/documentation/issues) that we'd
95love help with._
96
97- Robust and complete `JSDoc` support, including typedefs.
98- Strong support for HTML and Markdown output
99- Documentation coverage, statistics, and validation
100
101documentation is an OPEN Open Source Project. This means that:
102
103Individuals making significant and valuable contributions are given
104commit-access to the project to contribute as they see fit. This
105project is more like an open wiki than a standard guarded open source project.