Skip to content

Commit b3be70a

Browse files
soda-xsoda-x
committed
chore: add 3.4 en documents to en folder, add 3.4 zh-cn documents to zh-cn folder
1 parent 7c6367f commit b3be70a

36 files changed

+1576
-813
lines changed

‎README.md

Lines changed: 0 additions & 29 deletions
This file was deleted.

‎en/css-and-template.md

Lines changed: 87 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,87 @@
1+
# Handle css and template
2+
3+
---
4+
5+
Css and html template are significant parts in front-end development, and spm is just good for it.
6+
7+
## Css
8+
9+
The spm package could be a pure css package, use `main` and `output` to specify endpoint files.
10+
11+
For Example, there is a `main-style` package for our site layout:
12+
13+
```
14+
button.css
15+
tip.css
16+
index.css
17+
package.json
18+
```
19+
20+
```json
21+
{
22+
"name": "main-style",
23+
"version": "1.0.0",
24+
"spm": {
25+
"dependencies": {
26+
"normalize.css": "3.0.1"
27+
},
28+
"main": "index.css"
29+
}
30+
}
31+
```
32+
33+
Simply import files and other packages by a standard `@import`.
34+
35+
```
36+
/* index.css */
37+
@import url(http://github.com/'normalize.css');
38+
39+
@import url(http://github.com/'./button.css');
40+
@import url(http://github.com/'./tip.css');
41+
```
42+
43+
[alice-button](https://github.com/aliceui/button) is a nice example as well.
44+
45+
You can also require css package in js file, just like js package but without exports.
46+
47+
```
48+
require('main-style');
49+
var moment = require('moment');
50+
```
51+
52+
spm will use [import-style](http://spmjs.io/package/import-style) to import css package's content after building.
53+
54+
55+
## Template
56+
57+
Fisrtly, write your template in file, named it as `*.html` or `*.tpl` or `*.handlebars`.
58+
59+
```html
60+
<!-- defalut.tpl -->
61+
<div>
62+
<span>{{name}}</span>
63+
<span>{{content}}</span>
64+
</div>
65+
```
66+
67+
Then require it in js file.
68+
69+
```js
70+
var Handlebars = require('handlebars');
71+
var source = require('./defalut.tpl'); // string content of defalut.tpl
72+
73+
var template = Handlebars.compile(source); // compile it with your compiler
74+
var result = template({
75+
name: 'alex',
76+
content: 'content'
77+
});
78+
```
79+
80+
If the extension is `.handlebars`, `spm build` will precompile it and import [handlebars-runtime](http://spmjs.io/package/handlebars-runtime) automaticly for better perfermance, just similar with css's procedure.
81+
82+
83+
## Precompile language
84+
85+
People prefer a lot precompile languages both for css and template, such as [less](http://lesscss.org/), [scss](http://sass-lang.com/), [mustache](https://github.com/janl/mustache.js), [Hogan.js](https://github.com/twitter/hogan.js), [doT](https://github.com/olado/doT) and etc.
86+
87+
Consider [spm.scripts](/documentation/package.json#fields) in package.json for precompileing procedure.

‎en/develop-a-package.md

Lines changed: 198 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,198 @@
1+
# Develop A Package
2+
3+
---
4+
5+
You can follow the steps to develop a package using [spm](https://github.com/spmjs/spm).
6+
7+
```
8+
$ spm --version
9+
3.x.x
10+
```
11+
12+
Make sure that [email protected] is installed.
13+
14+
## init
15+
16+
```bash
17+
$ mkdir now
18+
$ cd now
19+
$ spm init
20+
```
21+
22+
```
23+
Creating a spm package:
24+
[?] Package name: (now)
25+
[?] Version: (1.0.0)
26+
[?] Description:
27+
[?] Author: afc163 <[email protected]>
28+
29+
Initialize a spm package Succeccfully!
30+
```
31+
32+
Then you have a package named `now`.
33+
34+
## Install dependencies
35+
36+
Install default devDependencies first.
37+
38+
```bash
39+
$ spm install
40+
```
41+
42+
We need [moment](http://momentjs.com) as a dependency which can be found [here](http://spmjs.io/package/moment).
43+
44+
```bash
45+
$ spm install moment --save
46+
```
47+
48+
## Code and Debug
49+
50+
Edit `index.js` as follow, just like nodejs.
51+
52+
```javascript
53+
// require module in spm.dependencies
54+
var moment = require('moment');
55+
56+
// require relative file in you project
57+
// var util = require('./util');
58+
59+
var now = moment().format('MMMM Do YYYY, h:mm:ss a');
60+
module.exports = now;
61+
```
62+
63+
Then edit `examples/index.md`:
64+
65+
<pre>
66+
# Demo
67+
68+
---
69+
70+
## Normal usage
71+
72+
````javascript
73+
var now = require('../index');
74+
console.log(now);
75+
````
76+
</pre>
77+
78+
79+
Run `spm doc` to start a documentation service at `127.0.0.1:8000` .
80+
81+
```bash
82+
$ spm doc
83+
```
84+
85+
Open [http://127.0.0.1:8000/examples/](http://127.0.0.1:8000/examples/) in browser to see the result.
86+
87+
Except using three &#96; in Markdown file, you can also use four &#96; to wrap your code.
88+
89+
It is a special rule that make your code highlighted and would be inserted to document page as a script block so they can be excuted at the same time. That is very useful for debugging your demo and writing a beautiful documentation both.
90+
91+
If you want to insert a iframe in your demo, make your code to `iframe` type.
92+
93+
<pre>
94+
````iframe:600
95+
I am in a iframe of 600px high
96+
````
97+
</pre>
98+
99+
100+
> If you don't want to debug your code by `spm doc`, you can try [seajs-wrap](https://github.com/seajs/seajs-wrap) or [spm-server](https://github.com/spmjs/spm-server/) to debug `CommonJS` modules in development.
101+
102+
## Add Test Case
103+
104+
Edit test file at `tests/now-spec.js`. We introduce a default assert solution [expect.js](http://spmjs.io/package/expect.js).
105+
106+
```javascript
107+
var expect = require('expect.js');
108+
var now = require('../index');
109+
110+
describe('now', function() {
111+
112+
it('normal usage', function() {
113+
expect(now).to.be.a('string'); // add this
114+
});
115+
116+
});
117+
```
118+
119+
See tests result.
120+
121+
```bash
122+
$ spm test
123+
```
124+
125+
You can also open [http://127.0.0.1:8000/tests/runner.html](http://127.0.0.1:8000/tests/runner.html) in browser.
126+
127+
## Publish
128+
129+
Now you have a great package having wonderful function and complete tests case, you can publish the package to [spmjs.io](http://spmjs.io/).
130+
131+
```bash
132+
$ spm publish
133+
```
134+
135+
You should run `spm login` first to get permission, otherwise it would propmt the authorization problem.
136+
137+
```bash
138+
$ spm login
139+
```
140+
141+
`username` is the name of your github account, and `authkey` can be found at http://spmjs.io/account after signing in.
142+
143+
> The package `now` is published by me, of cause. You should change other name and retry.
144+
145+
## Documentation
146+
147+
spmjs.io can host your package's documentation. What all you need to do is editing `README.md` and `examples` folder, preview it by `spm doc watch`, then publish it to spmjs.io.
148+
149+
```bash
150+
$ spm doc publish
151+
```
152+
153+
The documentation url is `http://spmjs.io/docs/{{name}}/` for latest version and `http://spmjs.io/docs/{{name}}/{{version}}/` for each versions.
154+
155+
For example, http://spmjs.io/docs/now/.
156+
157+
## Build
158+
159+
```bash
160+
$ spm build
161+
```
162+
163+
This command will build the files indicated by `spm.main` and `spm.output` field to `dist` folder. The `spm.buildArgs` would be executed as arguments.
164+
165+
The default build result is a package which could be deployed at cdn. Then you can use it by using [Sea.js](https://github.com/seajs/seajs/), [[email protected]](https://raw.githubusercontent.com/seajs/seajs/2.2.1/dist/sea.js) for example.
166+
167+
168+
```html
169+
<script src="http://cdn.example.com/path/to/sea.js"></script>
170+
<script src="http://cdn.example.com/path/to/seajs-combo.js"></script><!-- If your need that -->
171+
<script>
172+
seajs.config({
173+
base: 'http://cdn.example.com/',
174+
alias: {
175+
now: 'now/1.0.0/index.js'
176+
}
177+
});
178+
// load http://cdn.example.com/??now/1.0.0/index.js,moment/2.6.0/moment.js
179+
seajs.use(['now'], function(now) {
180+
console.log(now);
181+
});
182+
</script>
183+
```
184+
185+
And We strongly recommend building a [standalone](/documentation/spm-commands#spm-build) package by adding an argument.
186+
187+
```bash
188+
$ spm build --include standalone
189+
```
190+
191+
```html
192+
<!-- use it without loader -->
193+
<script src="http://cdn.example.com/path/to/standalone.js"></script>
194+
```
195+
196+
## Congratulation
197+
198+
Now you learn how to develop a package using spm, welcome to publish your packages here!

‎en/difference-from-2.x.md

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
# Difference From [email protected]
2+
3+
---
4+
5+
[[email protected]](https://github.com/spmjs/spm/tree/master) is new version of [[email protected]](https://github.com/spmjs/spm/tree/2.x), we have a collection of updates now.
6+
7+
- [spmjs.org](https://spmjs.org) is package service for [email protected], now is [spmjs.io](http://spmjs.io) which is prettier and easier to [deploy in your company](https://github.com/spmjs/spmjs.io/).
8+
9+
- Change spm profile from `~/.spm/spmrc` to `~/.spm/spmrc-3x`.
10+
11+
- `family` is removed from package.json.
12+
13+
- `spm.alias` is replaced by `spm.dependencies` now.
14+
15+
- `spm doc`, `spm init`, `spm build`, `spm test` are integrated to spm commands.
16+
17+
- [docs.spmjs.org](http://docs.spmjs.org) is old documentation for [email protected].
18+
19+
- No need to build first before publish, the package only contains source code. Building is needed just before using in your website.
20+
21+
- [迁移 spm2 到 spm3](https://github.com/spmjs/spm/wiki/%E8%BF%81%E7%A7%BB-spm2-%E7%9A%84%E6%A8%A1%E5%9D%97%E5%88%B0-spm3)

0 commit comments

Comments
 (0)