JPM

文档

A JUI Package Manager

是什么，做什么？

我们有一个 组件中心 用来展示组件，方便其他工程师了解有哪些组件，如何使用 JPM工具用来提交这个组件到组件中心，类似于Bower，我们提交的是组件的基本信息，然后组件中心收到提交会pull这个组件。所以组件必须是提交到我们阿里巴巴的gitlab上的。

什么是符合条件的组件，

1. 所在的仓库会提交到gitlab中
2. 符合下面的组件规范

提交一个组件流程

步骤1 安装依赖-> 步骤2 按组件规范编写组件 -> 步骤3 生成文档 -> 步骤4 发布组件

一个事例

asyncload

步骤1 安装依赖

npm install jsdoc -g
npm install ju-jpm -g

步骤2 组件规范

对组件目录结构的规范，以及package.json规范.

目录结构

组件文件夹目录结构

  index.js // 组件js
  index.html // 可运行的文档 非polymer通过jpm doc运行生成
  demo
    index.html  // 可运行的demo
  package.json // 描述组件信息

package.json规范

{
  // [必填]
  "name": "asyncload",
  // 默认index.js
  "main": "index.js",
  "description": "异步加载的脚本",
  // [必填] 必须是git@gitlab这种地址
  "giturl": "git@gitlab.alibaba-inc.com:ju/jui-gallery.git",
  // [必填] 组件的相对仓库根目录的路径
  "path": "src/asyncload",
  // 即组件所在的分支，即daily/0.1.2，取"0.1.2"
  "version": "0.1.2"
}

步骤2 文档生成(针对非polymer组件)

jpm组件网站，读取的文档的路径都是组件目录下的index.html.

1 polymer组件则遵循iron-component-page规范，组件目录下index.html的文档html即可。

2 非polymer组件，则要编写符合jsdoc规范的注释，手动执行jpm doc生成index.html

注释书写

文档会分几大部分，第一部分组件的说明介绍，第二部分组件的API，包括(Properties, Methods, Events, Behaviors非polymer没有)

** 第一部分 组件说明 **

放在index.js顶部，注释中必须标记上@fileOverview，支持Markdown语法。

// index.js
/**
 * @fileOverview  
 * 
 * Asyncload
 * 
 * ## 介绍
 *
 * 加载异步的数据
 *	
 * ## 如何使用
 * 
 * ```
 * <div class="J-asyncload" data-external="./external-fragment.html"></div>
 * KISSY.use('jui/0.1.2/asyncload/index', function (S, Asyncload) {
 * 	new Asyncload('.J-asyncload');
 * });
 * ```
 */

** 第二部分 API **

符合jsdoc的语法

事件描述符@event, 属性描述符 @member, 函数描述符 @function

/**
 * 写了一段事件
 * 
 * @event transitionend
 * @param {{node: Object}} detail Contains the animated node.
 */

属性注释

/**
 * 要渲染到的节点
 * 
 * @member render
 * @type {String}
 * @default ''
 */

/**
 * 获取select中的options选项的key-value映射
 * 
 * @function getActivityMap
 * @return {Object} activityMap
 */

文档生成工具()

jpm提供了

命令 jpm doc
在组件目录下执行jpm doc会解析index.js生成index.html的文档html，注：通过file://访问index.html会无效。需通过创建一个localhost的server来访问。

cd ~/work/jui-gallery
cd src/asyncload
jpm doc

步骤4 发布一个组件

演示项目是 jui-gallery仓库，组件asyncload在仓库下src/asyncload文件夹。

cd ~/work/jui-gallery
cd src/asyncload
jpm publish
或 jpm publish --tag=0.1.2 (自定义指定版本号)

一些说明

指定组件版本号

有三种版本号指定方式

版本号获取优先级：命令行指定 > package.json指定 > 自动获取当前git分支号

命令行指定

jpm publish --tag=<version> 如：jpm publish --tag=0.1.2

** package.json指定 **

即在package.json中version字段指定

** 自动获取当前git分支号 **

即工具会自动获取当前的git项目的分支

组件网站

http://mo.ju.taobao.net:3006/list

JPM开发者

本地起一个jpm的网站 DEBUG=jpm:* node web/index.js 发布组件到本地的jpm网站 jpm publish --debug=true

API接口

http://localhost:3006/api/publish?name=asyncload&version=0.0.1 http://localhost:3006/api/register?name=asyncload