1 | # FireDoc
|
2 |
|
3 | [![Circle CI](https://circleci.com/gh/cocos-creator/firedoc/tree/master.svg?style=shield)](https://circleci.com/gh/cocos-creator/firedoc/tree/master)
|
4 |
|
5 | API Doc generator rewritten from [YUIDoc](https://github.com/yui/yuidoc). We use this tool to self-document firedoc itself at:
|
6 |
|
7 | - English: http://cocos-creator.github.io/firedoc/ or http://cocos-creator.github.io/firedoc/en
|
8 | - 中文: http://cocos-creator.github.io/firedoc/zh
|
9 |
|
10 | [![NPM](https://nodei.co/npm/firedoc.png?stars&downloads)](https://nodei.co/npm/firedoc/)
|
11 |
|
12 |
|
13 | Overview
|
14 | --------
|
15 |
|
16 | FireDoc is forked and rewritten from [YUIDoc](https://github.com/yui/yuidoc) and added some powerful enhanced features at [Syntax Guide](GUIDE.md).
|
17 |
|
18 | > YUIDoc is a [Node.js](http://nodejs.org/) application used at build time to
|
19 | > generate API documentation for JavaScript code. YUIDoc is comment-driven and supports a wide
|
20 | > range of JavaScript coding styles. The output of YUIDoc is API documentation formatted as a
|
21 | > set of HTML pages including information about methods, properties, custom events and
|
22 | > inheritance for JavaScript objects.
|
23 |
|
24 | > YUIDoc was originally written for the YUI Project; it uses YUI JavaScript and CSS in the
|
25 | > generated files and it supports common YUI conventions like Custom Events. That said,
|
26 | > it can be used easily and productively on non-YUI code.
|
27 |
|
28 | Installation
|
29 | ------------
|
30 |
|
31 | ```sh
|
32 | $ npm install -g firedoc
|
33 | ```
|
34 |
|
35 | Usage
|
36 | -------
|
37 |
|
38 | ```
|
39 | Usage: firedoc [options] [command]
|
40 |
|
41 |
|
42 | Commands:
|
43 |
|
44 | build [path] build document from the directory
|
45 | install [path] install theme or plugin
|
46 | preview [path] build and preview the document from directory
|
47 | help [cmd] display help for [cmd]
|
48 |
|
49 | Options:
|
50 |
|
51 | -h, --help output usage information
|
52 | -V, --version output the version number
|
53 |
|
54 | ```
|
55 |
|
56 | Get Started
|
57 | -----------
|
58 |
|
59 | ```sh
|
60 | $ firedoc build <path> --lang <lang>
|
61 | ```
|
62 |
|
63 | Or using a shortcut command:
|
64 |
|
65 | ```sh
|
66 | $ firedoc <path> --lang <lang>
|
67 | ```
|
68 |
|
69 | The following is the helper of `firedoc-build(1)`:
|
70 |
|
71 | ```
|
72 | Usage: firedoc-build [options]
|
73 |
|
74 | Options:
|
75 |
|
76 | -h, --help output usage information
|
77 | -l --lint lint the parser
|
78 | --parse-only only parse
|
79 | -H --http build doc for web
|
80 | -M --markdown generate markdown docs
|
81 | -T --theme <dir> specify theme directory
|
82 | -D --dest <dir> the destination folder to build
|
83 | -L --lang <language> the i18n language
|
84 | -S --source whether or not output source files and show the link in 'Defined in' section.
|
85 | -v --verbose print all verbose information
|
86 | ```
|
87 |
|
88 | `--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.
|
89 |
|
90 |
|
91 | `--markdown` or `-M` is optional flag, which lets you get the markdown-based documentation to
|
92 | directly host at Github or Bitbucket. [Firedoc](https://github.com/fireball-x/firedoc)'s github
|
93 | hosted documentation is generated by itself.
|
94 |
|
95 | For sites that requires a base url (such as `http://mysite.com/docs`), specify a `baseurl` property in your `yuidoc.json` file:
|
96 |
|
97 | ```json
|
98 | {
|
99 | "name": "My Site",
|
100 | "baseurl": "/docs",
|
101 | "options": {
|
102 | "baseUrl": "",
|
103 | "outdir": "path/to/output",
|
104 | "linkNatives": true,
|
105 | "paths": [
|
106 | "path/to/my/src"
|
107 | ],
|
108 | "tabtospace": 4
|
109 | }
|
110 | }
|
111 | ```
|
112 |
|
113 | If you want to preview your api docs with local html files, add a
|
114 | ```json
|
115 | "local": "true"
|
116 | ```
|
117 |
|
118 | to your config file.
|
119 |
|
120 | Themes
|
121 | ------------
|
122 |
|
123 | By default the firedoc provides the following 3 themes:
|
124 |
|
125 | 1. [default](https://github.com/fireball-x/firedoc/tree/master/themes/default) the default theme of firedoc
|
126 | 2. [default(zh)](https://github.com/fireball-x/firedoc/tree/master/themes/default_zh) the Chinese version of default
|
127 | 3. [markdown](https://github.com/fireball-x/firedoc/tree/master/themes/markdown) the default markdown theme for firedoc
|
128 |
|
129 | #### Specify a theme locally
|
130 |
|
131 | ```
|
132 | firedoc build <path> --theme [path/to/your/theme]
|
133 | ```
|
134 |
|
135 | #### Install a theme remotely
|
136 |
|
137 | Firedoc supports that you can install a theme from [Github](https://github.com), [Bitbucket](https://bitbucket.org) or any other valid url.
|
138 |
|
139 | ```sh
|
140 | $ firedoc install notab
|
141 | $ firedoc install firedoc-theme-notab
|
142 | $ firedoc install https://github.com/fireball-x/firedoc-theme-notab
|
143 | ```
|
144 |
|
145 | The above command will install the theme [firedoc-theme-notab](https://github.com/fireball-x/firedoc-theme-notab) into installed firedoc directory in your machine. Then you would be able to use the theme just like this:
|
146 |
|
147 | ```sh
|
148 | $ firedoc build <path> --theme notab
|
149 | ```
|
150 |
|
151 | 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:
|
152 |
|
153 | ```sh
|
154 | $ firedoc install <url> --name different-theme-name
|
155 | ```
|
156 |
|
157 | If you are wanting to write a new theme and need some details, you could go to: [themes README](themes).
|
158 |
|
159 | **Note**: please make sure you have the installed following dependencies before using theme functionality:
|
160 |
|
161 | - Node.js or IO.js which supports:
|
162 | + Template string
|
163 | + Synchronous `child_prcess` spawn
|
164 | - `git` command-line tool
|
165 |
|
166 | Test
|
167 | -------------
|
168 |
|
169 | To run test
|
170 |
|
171 | ```sh
|
172 | $ npm test
|
173 | ```
|
174 |
|
175 | Documentation
|
176 | -------------
|
177 |
|
178 | * [User Guides](GUIDE.md)
|
179 | * [Change Logs](https://github.com/fireball-x/firedoc/releases)
|
180 | * [API Docs(markdown)](docs)
|
181 | * [API Docs(html)](http://fireball-x.github.io/firedoc/)
|
182 | * [中文文档](http://fireball-x.github.io/firedoc/zh/)
|
183 |
|
184 | Contributing
|
185 | ------------
|
186 |
|
187 | Please see the [CONTRIBUTING.md](CONTRIBUTING.md).
|
188 |
|
189 | License
|
190 | -------
|
191 |
|
192 | This software is free to use under the Yahoo Inc. BSD license. See the [LICENSE file](LICENSE) for license text and copyright information.
|