FireDoc

API Doc generator rewritten from YUIDoc. We use this tool to self-document firedoc itself at:

English: http://cocos-creator.github.io/firedoc/ or http://cocos-creator.github.io/firedoc/en
中文: http://cocos-creator.github.io/firedoc/zh

Overview

FireDoc is forked and rewritten from YUIDoc and added some powerful enhanced features at Syntax Guide.

YUIDoc is a Node.js application used at build time to generate API documentation for JavaScript code. YUIDoc is comment-driven and supports a wide range of JavaScript coding styles. The output of YUIDoc is API documentation formatted as a set of HTML pages including information about methods, properties, custom events and inheritance for JavaScript objects.

YUIDoc was originally written for the YUI Project; it uses YUI JavaScript and CSS in the generated files and it supports common YUI conventions like Custom Events. That said, it can be used easily and productively on non-YUI code.

Installation

$ npm install -g firedoc

Usage

Usage: firedoc [options] [command]


Commands:

  build [path]    build document from the directory
  install [path]  install theme or plugin
  preview [path]  build and preview the document from directory
  help [cmd]      display help for [cmd]

Options:

  -h, --help     output usage information
  -V, --version  output the version number

Get Started

$ firedoc build <path> --lang <lang>

Or using a shortcut command:

$ firedoc <path> --lang <lang>

The following is the helper of firedoc-build(1):

  Usage: firedoc-build [options]

  Options:

    -h, --help            output usage information
    -l --lint             lint the parser
    --parse-only          only parse
    -H --http             build doc for web
    -M --markdown         generate markdown docs
    -T --theme <dir>      specify theme directory
    -D --dest <dir>       the destination folder to build
    -L --lang <language>  the i18n language
    -S --source           whether or not output source files and show the link in 'Defined in' section.
    -v --verbose          print all verbose information

--lang option is required for multi-language description. Currently firedoc supports en and zh language option. Adding those option will generate docs for that specific language.

--markdown or -M is optional flag, which lets you get the markdown-based documentation to directly host at Github or Bitbucket. Firedoc's github hosted documentation is generated by itself.

For sites that requires a base url (such as http://mysite.com/docs), specify a baseurl property in your yuidoc.json file:

{
  "name": "My Site",
  "baseurl": "/docs",
  "options": {
    "baseUrl": "",
    "outdir": "path/to/output",
    "linkNatives": true,
    "paths": [
        "path/to/my/src"
    ],
    "tabtospace": 4
  }
}

If you want to preview your api docs with local html files, add a

"local": "true"

to your config file.

Themes

By default the firedoc provides the following 3 themes:

default the default theme of firedoc
default(zh) the Chinese version of default
markdown the default markdown theme for firedoc

Specify a theme locally

firedoc build <path> --theme [path/to/your/theme]

Install a theme remotely

Firedoc supports that you can install a theme from Github, Bitbucket or any other valid url.

$ firedoc install notab
$ firedoc install firedoc-theme-notab
$ firedoc install https://github.com/fireball-x/firedoc-theme-notab

The above command will install the theme firedoc-theme-notab into installed firedoc directory in your machine. Then you would be able to use the theme just like this:

$ firedoc build <path> --theme notab

However if the remote url has a same basename with what you have installed in your machine, then you can specify a different name to install it:

$ firedoc install <url> --name different-theme-name

If you are wanting to write a new theme and need some details, you could go to: themes README.

Note: please make sure you have the installed following dependencies before using theme functionality:

Node.js or IO.js which supports:
- Template string
- Synchronous child_prcess spawn
git command-line tool

Test

To run test

$ npm test

Documentation

Contributing

Please see the CONTRIBUTING.md.

License

This software is free to use under the Yahoo Inc. BSD license. See the LICENSE file for license text and copyright information.

Package detail

firedoc

readme