| 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 | [](https://circleci.com/gh/documentationjs/documentation/tree/master)
|
| 10 | [](http://badge.fury.io/js/documentation)
|
| 11 | [](https://gitter.im/documentationjs/documentation?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge)
|
| 12 | [](https://david-dm.org/documentationjs/documentation)
|
| 13 | [](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 |
|
| 42 | Globally install `documentation` using the [npm](https://www.npmjs.com/) package manager:
|
| 43 |
|
| 44 | ```sh
|
| 45 | $ npm install -g documentation
|
| 46 | ```
|
| 47 |
|
| 48 | This installs a command called `documentation` in your path, that you can
|
| 49 | point at [JSDoc](https://jsdoc.app/about-getting-started.html)-annotated source code to generate
|
| 50 | human-readable documentation. First, run `documentation` with the `--help`
|
| 51 | option for help:
|
| 52 |
|
| 53 | ```sh
|
| 54 | Usage:
|
| 55 |
|
| 56 | # generate markdown docs for index.js and files it references
|
| 57 | documentation build index.js -f md
|
| 58 |
|
| 59 | # generate html docs for all files in src, and include links to source files in github
|
| 60 | documentation build src/** -f html --github -o docs
|
| 61 |
|
| 62 | # document index.js, ignoring any files it requires or imports
|
| 63 | documentation build index.js -f md --shallow
|
| 64 |
|
| 65 | # validate JSDoc syntax in util.js
|
| 66 | documentation lint util.js
|
| 67 |
|
| 68 | # update the API section of README.md with docs from index.js
|
| 69 | documentation readme index.js --section=API
|
| 70 |
|
| 71 | # build docs for all values exported by index.js
|
| 72 | documentation build --document-exported index.js
|
| 73 |
|
| 74 | # build html docs for a TypeScript project
|
| 75 | documentation build index.ts --parse-extension ts -f html -o docs
|
| 76 |
|
| 77 | Commands:
|
| 78 | build [input..] build documentation
|
| 79 | lint [input..] check for common style and uniformity mistakes
|
| 80 | readme [input..] inject documentation into your README.md
|
| 81 |
|
| 82 | Options:
|
| 83 | --version Show version number [boolean]
|
| 84 | --help Show help [boolean]
|
| 85 | ```
|
| 86 |
|
| 87 | ## [Contributing](CONTRIBUTING.md)
|
| 88 |
|
| 89 | _We have plenty of
|
| 90 | [issues](https://github.com/documentationjs/documentation/issues) that we'd
|
| 91 | love help with._
|
| 92 |
|
| 93 | - Robust and complete `JSDoc` support, including typedefs.
|
| 94 | - Strong support for HTML and Markdown output
|
| 95 | - Documentation coverage, statistics, and validation
|
| 96 |
|
| 97 | documentation is an OPEN Open Source Project. This means that:
|
| 98 |
|
| 99 | Individuals making significant and valuable contributions are given
|
| 100 | commit-access to the project to contribute as they see fit. This
|
| 101 | project is more like an open wiki than a standard guarded open source project.
|