Skip to content

Commit b72c54a

Browse files
sorryccsorrycc
committed
Merge pull request spmjs#9 from spmjs/3.6
chore: add 3.6 en documents to en folder, move 3.6 zh-cn documents t…
2 parents 7c6367f + 1c7f424 commit b72c54a

14 files changed

+557
-0
lines changed

‎en/css-and-template.md

Lines changed: 106 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,106 @@
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 (css) '~normalize.css';
38+
39+
@import './button.css';
40+
@import './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+
53+
## Template
54+
55+
Fisrtly, write your template in file, named it as `*.html` or `*.tpl` or `*.handlebars`.
56+
57+
**Realtime Compile**
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+
71+
var Handlebars = require('handlebars');
72+
var source = require('./tpl/tpl.tpl');
73+
74+
var template = Handlebars.default.compile(source);
75+
var result = template({
76+
name: 'alex',
77+
content: 'content'
78+
});
79+
80+
console.log(result);
81+
```
82+
83+
*Precompile**
84+
85+
```html
86+
<!-- defalut.handlebars -->
87+
<div>
88+
<span>{{name}}</span>
89+
<span>{{content}}</span>
90+
</div>
91+
```
92+
93+
Then require it in js file.
94+
95+
```js
96+
97+
var source = require('./defalut.handlebars');
98+
var result = source({
99+
name: 'alex',
100+
content: 'content'
101+
});
102+
console.log(result);
103+
```
104+
105+
106+

‎en/develop-a-package.md

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

‎en/getting-started.md

Lines changed: 63 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,63 @@
1+
# Getting Started
2+
3+
---
4+
5+
## Introduction
6+
7+
[spm](https://github.com/spmjs/spm) is a powerful and integrated static package manager designed for browser-side solutions including JavaScript, CSS and template.
8+
9+
[![](https://i.alipayobjects.com/i/localhost/png/201404/2YQxOTYoFp.png)](https://github.com/spmjs/spm)
10+
11+
All packages in `spmjs.io` should be written in CommonJS, having a complete lifecycle management via [spm](https://github.com/spmjs/spm), including the following features:
12+
13+
- Initialization
14+
- Dependencies Management
15+
- Local Development
16+
- Publishing on [spmjs.io](http://spmjs.io)
17+
- Test Runner
18+
- Documentation Site Generator and Host
19+
- Build
20+
21+
[spmjs.io](http://spmjs.io/) is packages management service for spm. You can browse for packages you need, or publish your package here.
22+
23+
## Installation
24+
25+
```bash
26+
$ npm install spm -g
27+
```
28+
29+
## Basic Usage
30+
31+
Init a spm package.
32+
33+
```bash
34+
$ mkdir example
35+
$ cd example
36+
$ spm init
37+
```
38+
39+
Install dependencies.
40+
41+
```bash
42+
$ spm install jquery --save
43+
$ spm install [email protected] --save
44+
```
45+
46+
Publish the package to [spmjs.io](http://spmjs.io/)
47+
48+
```bash
49+
$ spm publish
50+
```
51+
52+
> You should run `spm login` first to get permission. The `authkey` will be displayed at http://spmjs.io/account after signing in.
53+
54+
Add `.spmignore` for ignoring useless files to avoid oversize of package.
55+
56+
## Contribution
57+
58+
Anyone is welcome to contribute by the following ways.
59+
60+
- [Bug reports](https://github.com/spmjs/spm/issues)
61+
- [Feature requests](https://github.com/spmjs/spm/issues)
62+
- [Pull requests](https://github.com/spmjs/spm/pulls)
63+
- Promote spm on your social network.

0 commit comments

Comments
 (0)