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