Generating documentation with YUIDoc is as simple as going to the top of your source tree and running:
```terminal $ yuidoc . ```However, you can configure YUIDoc's behavior further by providing command line options, a JSON configuration file, or even both. This section discusses the `yuidoc` command line tool in more detail.
Certain `yuidoc` command line options correspond to entries in the the `yuidoc.json` configuration file. Command line options always take priority.
```terminal {{>help}} ```Most documentation tools (including YUIDoc) involve some sort of build process. However, YUIDoc provides a unique feature that allows you to short-circuit this.
In server mode, YUIDoc fires up a small Node.js based server and begins parsing and displaying documentation in real time. This greatly speeds up the documentation authoring process, as you can edit your source code and preview changes with a simple browser reload, rather than waiting for a build.
To activate server mode on `localhost:3000`, run `yuidoc --server`. You can optionally specify an alternate port:
```terminal yuidoc --server or yuidoc --server 5000 ``` Then visit: ```terminal http://127.0.0.1:3000/ or http://127.0.0.1:5000/ ```Any changes you make to your YUIDoc comment blocks. will be reflected when you reload the browser. It's that simple!
NOTE: Server mode is not a replacement for building and hosting your documentation, just a handy previewing tool. For production, you should generate static HTML pages and host them on a real web server.
YUIDoc generates a `data.json` file after it parses your API documentation. The `external.data` config option enables you to import a YUIDoc `data.json` file from another project and mix it into your own documentation.
This feature is handy when you are extending another project and would like to link back to their API documentation. For example, importing YUI Library's `data.json` file would enable YUIDoc to automatically link back to `Base`, `EventTarget`, and other core YUI objects that your own API might be extending or mixing in.
Currently, importing external data enables YUIDoc to resolve HTML links `@extends` or `@use` keywords, but does not cause YUIDoc to generate complete documentation for the external API. Future versions of YUIDoc may provide the option to mix in the data natively and reproduce the external API right along with your own.
Create an `external` object under the `options` object in your `yuidoc.json` file and give it a property called `data` pointing to the URL of the external `data.json` file you wish to import. `data` can be a string or an array of strings.
``` { "options": { "external": { "data": "http://yuilibrary.com/yui/docs/api/data.json" } } } ```Also, you are able to give `base` data within `external` for external base URLs.
``` { "options": { "external": { "data": [ { "base": "http://emberjs.com/api/", "json": "http://builds.emberjs.com/tags/v1.5.1/ember-docs.json" }, { "base": "http://emberjs.com/api/", "json": "http://builds.emberjs.com/tags/v1.0.0-beta.6/ember-data-docs.json" } ] } } } ```NOTE: YUIDoc currently fetches external data on each run with no caching.
You can also store most YUIDoc configurables in a `yuidoc.json` file. As mentioned in the command line arguments section, command line options always take priority over `yuidoc.json` configuration values.
The `yuidoc.json` file must reside in a directory somewhere under where you execute `yuidoc`. YUIDoc will scan the tree for this file before doing anything else.
A short example `yuidoc.json` file would resemble:
``` { "name": "The Foo API", "description": "The Foo API: a library for doing X, Y, and Z", "version": "1.2.1", "url": "http://example.com/", "options": { "outdir": "../build/apidocs" } } ``` See below for more examples.| Name | Description |
|---|---|
| `name` | A short name for the project. |
| `description` | A one or two sentence description of the project. |
| `version` | The project's current version, as some kind of meaningful string. |
| `url` | The project's primary URL. This does not necessarily have to be the URL of the generated API documentation. |
| `logo` | The logo to add to the header of all generated HTML documentation. If you do not provide a header, YUIDoc will use the YUI logo by default. |
Within the `options` object, you can provide any of the following fields:
| Name | Description |
|---|---|
| `linkNatives` | Selects whether to autolink native types such as `String` and `Object` over to the Mozilla Developer Network. |
| `attributesEmit` | Selects whether YUIDoc should autogenerate documentation for change events generated by the YUI Attribute API. When a YUI attribute `foo` changes its value, YUI automatically fires a custom event named `fooChange`. Setting `attributesEmit` to `true` instructs YUIDoc to automatically generate documentation for each of these events. You can set this value to `false` if you think that your audience is well aware of change events and would not benefit from this extra verbiage. |
| `selleck` | Selects whether to add Selleck metadata. If `true`, YUIDoc searches for a `component.json` file above the source tree and attaches that data to the module data as extra information. |
| `ignorePaths` | Specifies an array of string paths to ignore when using shell globbing. This only removes top level items from the list to initally scan. Use `exclude` to remove specific directories. |
| `exclude` | Specify a comma separated list of names you want to exclude from parses when YUIDoc recurses the source tree. |
| `paths` | Specifies a single string `glob` or array of globs to use when searching the source tree for docs to parse. |
| `outdir` | Specifies the directory in which to place the rendered HTML files and assets. |
| `tabtospace` | Specifies the number of spaces each tab character in source code should be converted to when using YUIDoc's source code view. The default is 8. |
| `external.data` | Provides a link to an external `data.json` file to merge into the local api docs. For more information, refer to the external data example. |
| `markdown` | Options to pass to markdown-it, the Markdown compiler used to compile API descriptions. See the markdown-it API for details. |
| `preprocessor` | Specifies the array of your preprocessor script or npm package like `yuidoc-preprocessor-foo` that implements a preprocessor. See the example used preprocessor. |
This sample `yuidoc.json` file is used in the YUI 3 project:
``` { "name": "YUI 3", "description": "YUI 3 JavaScript Framework", "version": "3.5.0", "url": "http://yuilibrary.com/", "options": { "linkNatives": "true", "attributesEmit": "true", "selleck": "true", "ignorePaths": [ "simpleyui" ], "paths": "*/js", "outdir": "../api-js" } } ```This sample `yuidoc.json` file is used in the YUIDoc project itself:
``` { "name": "YUIDoc", "description": "YUIDoc documentation tool written in JavaScript", "version": "0.2.38", "url": "http://yuilibrary.com/projects/yuidoc", "logo": "http://yuilibrary.com/img/yui-logo.png", "options": { "external": { "data": "http://yuilibrary.com/yui/docs/api/data.json" }, "linkNatives": "true", "attributesEmit": "true", "paths": [ "./lib" ], "outdir": "./output/api" } } ```This sample `yuidoc.json` file used preprocessor option:
``` { "name": "My Project", "version": "1.0.0", "options": { "paths": "src", "preprocessor": ["./path/to/custom_doc_preprocessor.js", "yuidoc-preprocessor-foo"] } } ```