Using YUIDoc

Main Page > Basic Usage

Jump to Table of Contents

YUIDoc Configuration

YUIDoc supports two ways to configure its output: command line arguments and the yuidoc.json file.

JSON Configuration

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"
  }
}

The yuidoc.json file needs to live in a directory somewhere under where you will be executing yuidoc. YUIDoc will scan the tree for this file before doing anything else.

JSON Options

Project Information

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.

Below are a few of the options available.

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 scanning 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.
external.data Provides a link to an external data.json file to merge into the local api docs. See the external data example for more info.