| 1 | ## 安装
|
| 2 |
|
| 3 | 安装正式版
|
| 4 | > npm install ydoc -g
|
| 5 |
|
| 6 | 安装测试版 (有新功能但不稳定)
|
| 7 | > npm install ydoc@beta -g
|
| 8 |
|
| 9 | ## 构建命令
|
| 10 |
|
| 11 | > ydoc build [-t templatePath] [-p page] [-w] [-o dest]
|
| 12 |
|
| 13 | 读取配置，构建文档
|
| 14 |
|
| 15 | * `-w|--watch`: 监听变化自动构建
|
| 16 | * `-t|--template`: 参数为自定义模板路径
|
| 17 | * `-o|--output`: 输出目录
|
| 18 | * `-p|--page`: 指定编译某页，默认编译所有。（多个页面名可以逗号分开，例 -p index,demo）
|
| 19 |
|
| 20 | ## 初始化命令
|
| 21 |
|
| 22 | > ydoc init [-t templatePath]
|
| 23 |
|
| 24 | 初始项目，创建配置文件与自定义模板(-t)，默认生成 `ydoc.json` 配置文件。
|
| 25 |
|
| 26 | * `-t|--template`: 参数为自定义模板路径
|
| 27 |
|
| 28 |
|
| 29 | ## 配置文件
|
| 30 |
|
| 31 | 配置文件可以以 `ydoc.json` 或者 `ydocfile.js` 的形式出现。
|
| 32 |
|
| 33 | ### 静态文件形式
|
| 34 |
|
| 35 | `ydoc.json` 的内容是 `JSON`，支持注释。
|
| 36 |
|
| 37 | 示例：
|
| 38 |
|
| 39 | ```json
|
| 40 | {
|
| 41 | "name": "YDoc",
|
| 42 | ...
|
| 43 | }
|
| 44 | ```
|
| 45 |
|
| 46 | ### 动态脚本形式
|
| 47 |
|
| 48 | `ydocfile.js` 可以 `exports` 一个 `Object` 配置，也可以 `exports` 一个 `Function` 用于执行获取配置。
|
| 49 |
|
| 50 | 示例1：
|
| 51 |
|
| 52 | ```js
|
| 53 | module.exports = {
|
| 54 | "name": "YDoc",
|
| 55 | ...
|
| 56 | };
|
| 57 | ```
|
| 58 |
|
| 59 | 示例2：
|
| 60 |
|
| 61 | ```js
|
| 62 | module.exports = function() {
|
| 63 | return {
|
| 64 | "name": "YDoc",
|
| 65 | ...
|
| 66 | };
|
| 67 | };
|
| 68 | ```
|
| 69 |
|
| 70 | 示例3：(支持异步返回)
|
| 71 |
|
| 72 | ```js
|
| 73 | module.exports = function(callback) {
|
| 74 | // do someing
|
| 75 | callback({
|
| 76 | "name": "YDoc",
|
| 77 | ...
|
| 78 | });
|
| 79 | };
|
| 80 | ```
|
| 81 |
|
| 82 | ## 配置内容
|
| 83 |
|
| 84 | 示例:
|
| 85 |
|
| 86 | ```json
|
| 87 | {
|
| 88 | "name": "YDoc", // 标示 配置文件
|
| 89 | "dest": "path/to/destination", // 默认为 "doc"
|
| 90 | "examplePath": "./examples", // 示例代码路径 默认 "./"
|
| 91 | "template": "path/to/templte", // 默认使用 YDoc 内置的模板
|
| 92 | "instructionsInfoPath": "./demo/component", //使用说明 内容路径
|
| 93 | "instructionsUrlPath": "./demo/component", //使用说明demo路径
|
| 94 | "theme": "ocean", // 配置主题，默认没有主题
|
| 95 | "defaultGrammar": "javascript", // 默认高亮语法
|
| 96 | "mutiversion": { // 配置多版本切换，使用此功能需要切换到新的分支(此分支专门用于生成文档)，在新分支的配置文件中添加此配置项
|
| 97 | "docbranch": "doc", // 新分支(专门用于生成文档的分支)名称
|
| 98 | "versions":[{
|
| 99 | "name": "3.0", // 需要生成的版本名称
|
| 100 | "branch": "v3.0.0" // 需要生成的版本所在的git分支
|
| 101 | },{
|
| 102 | "name": "4.0",
|
| 103 | "branch": "v4.0.0"
|
| 104 | },{
|
| 105 | "name": "4.1",
|
| 106 | "branch": "v4.1.0"
|
| 107 | }] // 需要切换的版本信息
|
| 108 | },
|
| 109 | "options": { // 通用编译器配置
|
| 110 | "markdown": { // 对于 markdown 编译器进行统一配置
|
| 111 | "menuLevel": 2 //选取第几级 head 作为目录，默认 -1 没有目录
|
| 112 | },
|
| 113 | "foldcode": true, // 是否折叠示例code
|
| 114 | "foldparam": true, // 是否折叠param
|
| 115 | "foldsidenav": true, // 是否折叠侧边目录，默认不折叠
|
| 116 | "staticsidenav": true, // 侧边目录不折叠且不跟随页面滚动
|
| 117 | "insertCSS": ["./style/a.css","./style/b.css"], // 配置css路径，可覆盖默认样式； 相对路径需要配置resources路径
|
| 118 | "insertJS": ["./scripts/a.js"], // 配置js路径；相对路径需要配置resources路径
|
| 119 | "hasPageName": true //是否添加页面名称，默认关闭；(文件名不包含中文和特殊字符)
|
| 120 | },
|
| 121 | "resources": { // 将配置的文件夹拷贝至生成文档的文件夹下
|
| 122 | "images": "./test-reactweb/docs/images/",
|
| 123 | "demo":"./test-reactweb/docs/demo/",
|
| 124 | "style": "./style/", // 指定insertCss后，配置css的目录
|
| 125 | "scripts": "./scripts/", // 指定insertJS后，配置js的目录
|
| 126 | },
|
| 127 | "common": { // 通用默认配置，包括主页配置等
|
| 128 | "title": "YDoc", //page title
|
| 129 | "footer": "© 2017 <a href=\"http://ued.qunar.com/ymfe/\">YMFE</a> Team. Build by <a href=\"http://ued.qunar.com/ydoc/\">ydoc</a>.", // 通用尾
|
| 130 | "home": "YMFE", // logo
|
| 131 | "homeUrl": "http://ued.qunar.com/ymfe/" // logourl
|
| 132 | },
|
| 133 | "pages": [{
|
| 134 | "name": "index", // Page Name 会根据他生成 html 文件，例: index.html
|
| 135 | "title": "开始", // Page Title
|
| 136 | "homepage": { // 配置首页，样式区别于其他页面
|
| 137 | "version": "v3.0.0", // 版本信息将显示在banner底部
|
| 138 | "button": [{ // 按钮组将显示在banner底部
|
| 139 | "name": " 起步 ",
|
| 140 | "href": "./start.html"
|
| 141 | },{
|
| 142 | "name": "Github",
|
| 143 | "href": "https://github.com/YMFE/ydoc"
|
| 144 | }],
|
| 145 | "intro": [{ // 首页的正文部分，数组项依次渲染，可重复使用
|
| 146 | "title": "为前端开发者设计的文档生成工具", // 介绍板块标题
|
| 147 | "desc": "YDoc让文档开发更简单高效，让开发者专注于程序本身，让项目代码更具可读性、可维护性。" // 介绍板块描述
|
| 148 | },{
|
| 149 | "title": "特性",
|
| 150 | "detail": {
|
| 151 | "type": "thumbnail", // 三列布局的介绍板块
|
| 152 | "content": [{ // 三列布局的内容，每项的key值非必需，但建议每列的key值一致
|
| 153 | "name": "丰富、可扩展的API", // 板块名称
|
| 154 | "src": "http://ojk406wln.bkt.clouddn.com/intro_muti.png", // 缩略图
|
| 155 | "desc": "YDoc提供了非常详尽的API，扩展性较强，如果你希望添加某些功能，可以在<a href=\"https://github.com/YMFE/ydoc\" target=\"_blank\"> Github </a>上面提Issue。" // 描述
|
| 156 | },{
|
| 157 | "name": "基于注释/markdown",
|
| 158 | "src": "http://ojk406wln.bkt.clouddn.com/intro_md.png",
|
| 159 | "desc": "基于项目代码注释与markdown快速构建文档，二者亦可在同一页面中使用。"
|
| 160 | },{
|
| 161 | "name": "可配置主题",
|
| 162 | "src": "http://ojk406wln.bkt.clouddn.com/intro_theme.png",
|
| 163 | "desc": "官方提供多套主题，并且支持用户自定义开发主题。"
|
| 164 | }]
|
| 165 | }
|
| 166 | }]
|
| 167 | },
|
| 168 | "banner": { // Banner 配置
|
| 169 | "title": "YDoc",
|
| 170 | "description": "开始"
|
| 171 | },
|
| 172 | "content": "./README.md", // 内容
|
| 173 | "compile": "markdown", // 解析器，如果内容有固定的扩展名，此项可忽略
|
| 174 | "options": { // 此 Page 用的编译器的配置
|
| 175 | "menuLevel": 2,
|
| 176 | "foldsidenav": true // 是否折叠侧边目录(优先级高于通用编译器配置)
|
| 177 | }
|
| 178 | }, {
|
| 179 | "name": "hybird",
|
| 180 | "title": "混合开发",
|
| 181 | "intro": "document/README.md", // 介绍 introduction
|
| 182 | "content": { // 单页多模块配置
|
| 183 | "sidebar": true, // 是否显示侧边目录
|
| 184 | "blocks": [{
|
| 185 | "name": "简介", // 标题
|
| 186 | "content": "document/hybrid/README.md" // 内容
|
| 187 | }, {
|
| 188 | "name": "Hybrid" // 只有标题，做目录和分割用
|
| 189 | }, {
|
| 190 | "name": "说明",
|
| 191 | "sub": true, // 标题在目录里已子目录形式显示
|
| 192 | "content": "modules/hybrid/framework/README.md"
|
| 193 | }]
|
| 194 | }
|
| 195 | }, {
|
| 196 | "name": "component",
|
| 197 | "title": "组件",
|
| 198 | "banner": {
|
| 199 | "title": "移动端组件",
|
| 200 | "description": "组件"
|
| 201 | },
|
| 202 | "content": { // 多页配置，multi 为 true
|
| 203 | "sidebar": true, //是否显示侧边目录
|
| 204 | "multi": true, // 多页配置
|
| 205 | "index": "./Libraries/extension/INTRO.md", // 首页配置
|
| 206 | "pages": [{ // 每页配置
|
| 207 | "name": "ListView",
|
| 208 | "index": "list", // 修改默认路径名
|
| 209 | "content": "./Libraries/extension/libs/ListView/QListView.js"
|
| 210 | }, {
|
| 211 | "name": "ScrollView",
|
| 212 | "content": "./Libraries/extension/libs/ScrollView/ScrollView.js"
|
| 213 | }]
|
| 214 | }
|
| 215 | }]
|
| 216 | }
|
| 217 | ```
|
| 218 |
|
| 219 | ### 解析器配置
|
| 220 |
|
| 221 | #### js
|
| 222 |
|
| 223 | 支持文件类型：`.js`，`.jsx`
|
| 224 | type字段配置的 `component` 和 `lib`，二者所支持的注释规则有所区别，参见[注释规则](./comment.html)。
|
| 225 |
|
| 226 | ```json
|
| 227 | {
|
| 228 | "type": "component", // 类型，可选 component 和 lib ，默认 component
|
| 229 | "source": false // 是否生成源文件预览，默认 false
|
| 230 | }
|
| 231 | ```
|
| 232 |
|
| 233 | #### css
|
| 234 |
|
| 235 | 支持文件类型：`.css`，`.sass`，`.scss`
|
| 236 |
|
| 237 | ```json
|
| 238 | {
|
| 239 | "source": false // 是否生成源文件预览，默认 false
|
| 240 | }
|
| 241 | ```
|
| 242 |
|
| 243 | #### markdown
|
| 244 |
|
| 245 | 支持文件类型：`.md`，`.markdown`
|
| 246 |
|
| 247 | ```json
|
| 248 | {
|
| 249 | "menuLevel": 2, // 选取第几级 head 作为目录，默认 -1 没有目录
|
| 250 | "subMeneLevel": 3 // 选取第几级 head 作为子目录，默认 menuLevel + 1
|
| 251 | }
|
| 252 | ```
|