atool-doc 基本使用

hello-world

atool-doc 是面相组件的静态 Demo 生成、调试工具，是一个更灵活、和组件结合更紧密的 codePen

如果你开发了一个组件：

  • 你需要本地写个 demo 把组件用起来看效果
  • 你需要编写介绍组件如何使用的例子，并且希望同时展示代码和代码运行效果
  • 你需要把例子打包成静态文件发送给组件使用者或部署在服务器上


那么你就需要 atool-doc

atool-doc 打包生成 Demo 时做了哪些事？

  • 如图，将每一个 example 文件都打包成可以访问的 html，并通过 index.html 管理起来


有没有使用 atool-doc 生成的例子可以看下？


before

  1. ./
  2. ├── README.md
  3. └── examples
  4.     ├── a.js
  5.     ├── a.html
  6.     └── b.md

after

  1. ./
  2. ├── README.md
  3. ├── __site
  4. │   ├── common.js
  5. │   ├── examples
  6. │   │   ├── a.html
  7. │   │   ├── a.js
  8. │   │   ├── b.html
  9. │   │   ├── b.js
  10. │   └── index.html
  11. └── examples
  12.     ├── a.js
  13.     ├── a.html
  14.     └── b.md

安装

  1. $ tnpm i atool-doc --save-dev

命令行参数

  1.   atool-doc          start server at http://127.0.0.1:8002 for demo
  3.   atool-doc [options]
  5.     -h, --help       output usage information
  6.     -v, --version    output the version number
  7.     --dest <dir>     config path of output dir, default __site
  8.     --source <dir>   config path of demo files dir, default examples
  9.     --tpl <path>     config path or name of tpl file
  10.     --config <path>  config path of webpack.config, default webpack.config.js
  11.     --port <number>  specify server port, default 8002
  12.     --build          only build
  13.     -w, --watch      using with --build, watch mode

编写你的第一个 Demo 文件

  • Demo 默认存放在 examples 文件夹，在该文件夹下新建你的第一个 Demo 文件

    1. $ md examples && vi examples/basic.md

  • 在 ## code 节点写下你需要生效的代码，在其他节点编写描述

    此处的 ## code 是保留字段，支持 js/jsx/javascript、css 和 html 三种格式来 自定义样式和预留的 Dom 结构

    可以模仿如图的方式进行编写，也可以参阅 custom.md

    image

  • 执行 atool-doc

    1. $ node_modules/.bin/atool-doc           # 启动本地 server，监听文件变化，查看 Demo 效果,  http://127.0.0.1:8002
    2. $ node_modules/.bin/atool-doc --build   # 打包 demo 到 __site 目录

  • 可选 可将 atool-doc 命令增加到 package.json，简化操作

    1. {
    2.   ...
    3.   "scripts": {
    4.     "doc-build": "atool-doc --build",
    5.     "doc": "atool-doc"
    6.   }
    7. }
    1. $ npm run doc
    2. $ npm run doc-build

  • 文档自动部署

你可以通过 Github 的 gh-pages 功能来实现更新 github 代码时，自动更新对应的 Demo 文件到服务器，在线访问！

  • 安装 gh-pages

    1. $ npm i gh-pages --save-dev

  • 添加命令到 package.json

    1. {
    2.   "scripts": {
    3.     "gh-pages": "npm run doc-build && gh-pages -d __site"
    4.   }
    5. }

  • 推送代码后运行 npm run gh-pages

在 https://yourGroup.github.io/yourProject/ 就会自动更新在线的 Demo 啦！

了解更多 atool-doc