added browser-sync, modified shred-single-dir in doc-shredder to return a promise, updated readme.
This commit is contained in:
Jay Traband
YuCheng Hu
parent
ac2bfed40d
commit
24948fde50
58
README.md
58
README.md
|
|
@ -1,36 +1,46 @@
|
|||
# 注意
|
||||
# Angular.io
|
||||
Angular.io is currently the preview site for Angular 2. This site also includes links to other helpful angular resources including Angular 1, Angular Material, and AngularFire.
|
||||
|
||||
master分支下是老版本的文档，新版本的文档位于aio分支下。目前aio只是部署到了 <https://angular.cn>，但尚未撰写中文的部署指南，不过你可以尝试自行按照英文版的readme.md进行部署。
|
||||
## How you can help
|
||||
- [File an issue on github](https://github.com/angular/angular.io/issues)
|
||||
- [Contribute to Angular.io](https://github.com/angular/angular.js/blob/master/CONTRIBUTING.md)
|
||||
|
||||
# angular.io 中文版
|
||||
|
||||
这里是 angular.io 字幕组，哦不对，是汉化组。译者汪志成 (雪狼)、叶志敏 (Rex) 和杨林 (todoubaba) 欢迎您的到访。
|
||||
## Development Setup
|
||||
1. Install version 0.17 of [Harp](http://harpjs.com/) (This is the current harp version.)
|
||||
2. cd into root directory `angular.io/`
|
||||
3. run `harp server`
|
||||
4. Open this url in the browser: [http://localhost:9000/](http://localhost:9000/)
|
||||
|
||||
我们将和官方英文版保持同步翻译，并同步发布到国内镜像 - <https://angular.cn>。
|
||||
## Development setup with watches
|
||||
1. cd into root directory `angular.io/`
|
||||
2. run `gulp serve-and-watch`
|
||||
3. Open this url in the browser: [http://localhost:9000/](http://localhost:9000/)
|
||||
4. Refresh your browser to see any changes.
|
||||
|
||||
## 授权协议
|
||||
## Development setup with watches and browser reload
|
||||
1. cd into root directory `angular.io/`
|
||||
2. install `browser-sync`
|
||||
|
||||
本文档遵循[“保持署名—非商用”创意共享4.0许可证（CC BY-NC 4.0）](http://creativecommons.org/licenses/by-nc/4.0/deed.zh)，请在**保持署名**、**非商用**的前提下自由使用，你甚至可以把它架设在自己的电脑或内网服务器上。
|
||||
`npm install -g browser-sync`<br/>
|
||||
|
||||
特别是：
|
||||
*or on Windows*<br/>
|
||||
|
||||
- **不得去掉**“关于中文版”的入口链接，也不得增删改“关于中文版”页的内容。
|
||||
- 如果您是**商业网站（包括但不限于任何有广告或收费的网站）**要发布或转载，请联系我们 <asnowwolf@gmail.com> 和 <rexebin@gmail.com>。
|
||||
`npm install -g browser-sync --msvs_version=2013`
|
||||
|
||||
**违反上述授权协议将面临法律追究。**
|
||||
3. run `gulp serve-and-sync`
|
||||
4. browser will launch ( on localhost:3000 instead of localhost:9000) and stay refreshed automatically.
|
||||
|
||||
## 编译与发布
|
||||
## Technology Used
|
||||
- Angular 1.x: The production ready version of Angular
|
||||
- Angular Material: An implementation of Material Design in Angular.js
|
||||
- Harp: The static web server with built-in preprocessing.
|
||||
- Sass: A professional grade CSS extension language
|
||||
- Normalize: A modern, HTML5-ready alternative to CSS resets
|
||||
- Grids: A highly customizable CSS Grid Framework built with Sass
|
||||
- Prettify: A JS module and CSS for syntax highlighting of source code snippets.
|
||||
- Icomoon: Custom built icon fonts
|
||||
|
||||
1. 用`git clone https://github.com/angular/angular-cn.git`把本项目取到本地。
|
||||
1. 用`git clone https://github.com/angular/angular.git`把 Angular 的源码取到本地。它将用来编译出 API 文档。
|
||||
1. 进入`angular-cn`目录
|
||||
1. 运行`npm install`安装依赖包
|
||||
1. 运行`gulp serve-and-sync-devguide`命令进行本地预览
|
||||
1. 运行`gulp build-compile --lang="(ts|js)"`命令进行编译
|
||||
1. 把`./www`目录发布到任何静态文件服务器上
|
||||
|
||||
如果是内网服务器，你还可以通过自建 CI 进行同步更新。
|
||||
|
||||
## 更多信息
|
||||
|
||||
关于本中文版以及三位译者的更多信息，请参见[“关于中文版”](https://angular.cn/translations/cn/home)链接。
|
||||
## License
|
||||
Powered by Google ©2010-2015. Code licensed under the [Apache License, Version 2.0](http://www.apache.org/licenses/LICENSE-2.0). Documentation licensed under [CC BY 3.0](http://creativecommons.org/licenses/by/3.0/).
|
||||
|
|
|
|||
42
gulpfile.js
42
gulpfile.js
|
|
@ -1,13 +1,12 @@
|
|||
var gulp = require('gulp');
|
||||
var watch = require('gulp-watch');
|
||||
var gutil = require('gulp-util');
|
||||
var Dgeni = require('dgeni');
|
||||
var path = require('path');
|
||||
var del = require('del');
|
||||
|
||||
var docShredder = require('./public/doc-shredder/doc-shredder');
|
||||
|
||||
var shredOptions = {
|
||||
var _shredOptions = {
|
||||
basePath: path.resolve('./public/docs'),
|
||||
sourceDir: "_examples",
|
||||
destDir: "_fragments"
|
||||
|
|
@ -21,32 +20,49 @@ a ‘partial’ shredder. It only shred’s files in directories changed during
|
|||
the current session.
|
||||
*/
|
||||
|
||||
gulp.task('serve-and-sync', function (cb) {
|
||||
execCommands(['harp server'], {}, cb);
|
||||
|
||||
gulp.task('shred-full', ['shred-clean'], function() {
|
||||
docShredder.shred( shredOptions);
|
||||
var browserSync = require('browser-sync').create();
|
||||
browserSync.init({
|
||||
proxy: 'localhost:9000',
|
||||
files: "public/docs/**/*/**/*",
|
||||
logFileChanges: true,
|
||||
reloadDelay: 500
|
||||
});
|
||||
|
||||
shredWatch(_shredOptions, function() {
|
||||
browserSync.reload();
|
||||
});
|
||||
});
|
||||
|
||||
gulp.task('serve-and-watch', function (cb) {
|
||||
var pattern = path.join(shredOptions.basePath, shredOptions.sourceDir, "**/*.*");
|
||||
|
||||
execCommands(['harp server'])
|
||||
|
||||
watch([ pattern], function(event, done) {
|
||||
console.log('Event type: ' + event.event); // added, changed, or deleted
|
||||
console.log('Event path: ' + event.path); // The path of the modified file
|
||||
docShredder.shredSingleDir(shredOptions, event.path);
|
||||
execCommands(['harp server'], {}, cb);
|
||||
shredWatch(_shredOptions);
|
||||
});
|
||||
|
||||
gulp.task('shred-full', ['shred-clean'], function() {
|
||||
docShredder.shred( _shredOptions);
|
||||
});
|
||||
|
||||
gulp.task('shred-clean', function(cb) {
|
||||
var cleanPath = path.join(shredOptions.basePath, shredOptions.destDir, '**/*.*')
|
||||
var cleanPath = path.join(_shredOptions.basePath, _shredOptions.destDir, '**/*.*')
|
||||
del([ cleanPath, '!**/*.ovr.*'], function (err, paths) {
|
||||
// console.log('Deleted files/folders:\n', paths.join('\n'));
|
||||
cb();
|
||||
});
|
||||
});
|
||||
|
||||
function shredWatch(shredOptions, postShredAction) {
|
||||
var pattern = path.join(shredOptions.basePath, shredOptions.sourceDir, "**/*.*");
|
||||
watch([pattern], function (event, done) {
|
||||
console.log('Event type: ' + event.event); // added, changed, or deleted
|
||||
console.log('Event path: ' + event.path); // The path of the modified file
|
||||
docShredder.shredSingleDir(shredOptions, event.path).then(function () {
|
||||
postShredAction && postShredAction();
|
||||
});
|
||||
});
|
||||
}
|
||||
|
||||
// added options are: shouldLog
|
||||
// cb is function(err, stdout, stderr);
|
||||
|
|
|
|||
75
package.json
75
package.json
|
|
@ -2,75 +2,36 @@
|
|||
"name": "angular.io",
|
||||
"version": "0.0.0",
|
||||
"private": true,
|
||||
"description": "Angular documentation",
|
||||
"description": "Angular 2 documentation",
|
||||
"main": "index.js",
|
||||
"scripts": {
|
||||
"test": "echo \"Error: no test specified\" && exit 1",
|
||||
"harp": "harp",
|
||||
"live-server": "live-server",
|
||||
"test-api-builder": "jasmine-node tools/api-builder",
|
||||
"protractor": "protractor"
|
||||
"test": "echo \"Error: no test specified\" && exit 1"
|
||||
},
|
||||
"repository": {
|
||||
"type": "git",
|
||||
"url": "https://github.com/angular/angular.io.git"
|
||||
"type": "git"
|
||||
},
|
||||
"license": "MIT",
|
||||
"licenses": [
|
||||
{
|
||||
"type": "Apache",
|
||||
"url": "http://www.apache.org/licenses/LICENSE-2.0.html"
|
||||
}
|
||||
],
|
||||
"bugs": {
|
||||
"url": ""
|
||||
},
|
||||
"devDependencies": {
|
||||
"archiver": "^1.0.0",
|
||||
"assert-plus": "^1.0.0",
|
||||
"bootstrap": "3.3.6",
|
||||
"broken-link-checker": "0.7.1",
|
||||
"browser-sync": "^2.9.3",
|
||||
"canonical-path": "0.0.2",
|
||||
"cheerio": "^0.20.0",
|
||||
"codelyzer": "0.0.26",
|
||||
"cross-spawn": "^4.0.0",
|
||||
"del": "^2.2.0",
|
||||
"del": "^1.2.0",
|
||||
"dgeni": "^0.4.0",
|
||||
"dgeni-packages": "^0.16.0",
|
||||
"diff": "^2.1.3",
|
||||
"fs-extra": "^0.30.0",
|
||||
"globby": "^4.0.0",
|
||||
"gulp": "4.0.2",
|
||||
"gulp-env": "0.4.0",
|
||||
"gulp-less": "^3.1.0",
|
||||
"gulp-sass": "^2.3.2",
|
||||
"gulp-task-listing": "^1.0.1",
|
||||
"gulp-tslint": "^5.0.0",
|
||||
"dgeni-packages": "^0.10.0",
|
||||
"gulp": "^3.5.6",
|
||||
"gulp-util": "^3.0.6",
|
||||
"gulp-watch": "^4.3.4",
|
||||
"harp": "^0.21.0",
|
||||
"html2jade": "^0.8.4",
|
||||
"indent-string": "^2.1.0",
|
||||
"jasmine-core": "^2.3.4",
|
||||
"jasmine-node": "^1.14.5",
|
||||
"jsdom": "^9.2.1",
|
||||
"jsonfile": "^2.2.2",
|
||||
"karma": "^0.13.10",
|
||||
"karma-chrome-launcher": "^1.0.1",
|
||||
"karma-jasmine": "^1.0.2",
|
||||
"live-server": "^1.0.0",
|
||||
"lodash": "^4.13.1",
|
||||
"marked": "^0.3.5",
|
||||
"minimatch": "^3.0.0",
|
||||
"mkdirp": "^0.5.1",
|
||||
"node-html-encoder": "0.0.2",
|
||||
"nodegit": "0.27.0",
|
||||
"path": "^0.12.7",
|
||||
"prompt": "^1.0.0",
|
||||
"protractor": "^3.0.0",
|
||||
"q": "^1.4.1",
|
||||
"tree-kill": "^1.0.0",
|
||||
"tslint": "^3.15.1",
|
||||
"typescript": "~2.0.10",
|
||||
"yargs": "^4.7.1"
|
||||
"lodash": "^3.10.1",
|
||||
"path": "^0.11.14",
|
||||
"q": "^1.4.1"
|
||||
},
|
||||
"dependencies": {
|
||||
"jstransformer-marked": "^1.0.1"
|
||||
},
|
||||
"homepage": "http://angular.io/"
|
||||
"contributors": [
|
||||
"Jay Traband <jayt@ideablade.com>"
|
||||
]
|
||||
}
|
||||
|
|
|
|||
|
|
@ -0,0 +1,136 @@
|
|||
// Canonical path provides a consistent path (i.e. always forward slashes) across different OSes
|
||||
var path = require('canonical-path');
|
||||
var Q = require('q');
|
||||
var del = require('del');
|
||||
// delPromise is a 'promise' version of del
|
||||
var delPromise = Q.denodeify(del);
|
||||
var Dgeni = require('dgeni');
|
||||
var _ = require('lodash');
|
||||
|
||||
var createPackage = function(shredOptions) {
|
||||
var shredder = new Dgeni.Package('doc-shredder', [
|
||||
// require('dgeni-packages/base') - doesn't work
|
||||
]);
|
||||
shredder.options = resolveOptions(shredOptions);
|
||||
return configure(shredder);
|
||||
};
|
||||
|
||||
var resolveOptions = function(shredOptions) {
|
||||
return _.defaults({}, shredOptions, {
|
||||
basePath: path.resolve('.'),
|
||||
// read files from any subdir under here
|
||||
sourceDir: "docs/_examples",
|
||||
// shredded files get copied here with same subdir structure.
|
||||
destDir: "docs/_fragments",
|
||||
// whether to include subdirectories when shredding.
|
||||
includeSubdirs: true
|
||||
});
|
||||
}
|
||||
|
||||
var shred = function(shredOptions) {
|
||||
try {
|
||||
var pkg = createPackage(shredOptions);
|
||||
var dgeni = new Dgeni([ pkg]);
|
||||
return dgeni.generate();
|
||||
} catch(x) {
|
||||
console.log(x.stack);
|
||||
throw x;
|
||||
}
|
||||
}
|
||||
|
||||
var shredSingleDir = function(shredOptions, filePath) {
|
||||
shredOptions = resolveOptions(shredOptions);
|
||||
var root = path.resolve(shredOptions.basePath, shredOptions.sourceDir);
|
||||
var fileDir = path.dirname(filePath);
|
||||
var relativePath = path.relative(root, fileDir);
|
||||
var sourceDir = path.join(shredOptions.sourceDir, relativePath);
|
||||
var destDir = path.join(shredOptions.destDir, relativePath);
|
||||
var options = {
|
||||
basePath: shredOptions.basePath,
|
||||
includeSubdirs: false,
|
||||
sourceDir: sourceDir,
|
||||
destDir: destDir
|
||||
}
|
||||
var cleanPath = path.join(shredOptions.basePath, destDir, '*.*')
|
||||
return delPromise([ cleanPath, '!**/*.ovr.*']).then(function(paths) {
|
||||
// console.log('Deleted files/folders:\n', paths.join('\n'));
|
||||
return shred(options);
|
||||
});
|
||||
}
|
||||
|
||||
module.exports = {
|
||||
shred: shred,
|
||||
shredSingleDir: shredSingleDir,
|
||||
createPackage: createPackage,
|
||||
resolveOptions: resolveOptions
|
||||
};
|
||||
|
||||
function configure(shredder) {
|
||||
var options = shredder.options;
|
||||
shredder
|
||||
.processor(require('dgeni-packages/base/processors/read-files'))
|
||||
.processor(require('dgeni-packages/base/processors/write-files'))
|
||||
.factory(require('dgeni-packages/base/services/writefile'))
|
||||
|
||||
// Ugh... Boilerplate that dgeni needs to sequence operations
|
||||
.processor({ name: 'reading-files' })
|
||||
.processor({ name: 'files-read', $runAfter: ['reading-files'] })
|
||||
.processor({ name: 'processing-docs', $runAfter: ['files-read'] })
|
||||
.processor({ name: 'docs-processed', $runAfter: ['processing-docs'] })
|
||||
.processor({ name: 'adding-extra-docs', $runAfter: ['docs-processed'] })
|
||||
.processor({ name: 'extra-docs-added', $runAfter: ['adding-extra-docs'] })
|
||||
.processor({ name: 'computing-ids', $runAfter: ['extra-docs-added'] })
|
||||
.processor({ name: 'ids-computed', $runAfter: ['computing-ids'] })
|
||||
.processor({ name: 'computing-paths', $runAfter: ['ids-computed'] })
|
||||
.processor({ name: 'paths-computed', $runAfter: ['computing-paths'] })
|
||||
.processor({ name: 'rendering-docs', $runAfter: ['paths-computed'] })
|
||||
.processor({ name: 'docs-rendered', $runAfter: ['rendering-docs'] })
|
||||
.processor({ name: 'writing-files', $runAfter: ['docs-rendered'] })
|
||||
.processor({ name: 'files-written', $runAfter: ['writing-files'] })
|
||||
|
||||
.factory(require('./fileShredder'))
|
||||
.factory(require('./regionExtractor'))
|
||||
.processor(require('./mdWrapperProcessor'))
|
||||
|
||||
.config(function(log) {
|
||||
// Set logging level
|
||||
log.level = 'info';
|
||||
})
|
||||
|
||||
|
||||
.config(function(readFilesProcessor, fileShredder ) {
|
||||
readFilesProcessor.fileReaders = [ fileShredder];
|
||||
})
|
||||
|
||||
// default configs - may be overriden
|
||||
.config(function(readFilesProcessor) {
|
||||
|
||||
// Specify the base path used when resolving relative paths to source and output files
|
||||
readFilesProcessor.basePath = options.basePath;
|
||||
|
||||
// Specify collections of source files that should contain the documentation to extract
|
||||
var extns = ['*.js', '*.html', '*.ts', '*.css' ];
|
||||
var includeFiles = extns.map(function(extn) {
|
||||
if (options.includeSubdirs) {
|
||||
return path.join(options.sourceDir, '**', extn);
|
||||
} else {
|
||||
return path.join(options.sourceDir, extn);
|
||||
}
|
||||
});
|
||||
readFilesProcessor.sourceFiles = [
|
||||
{
|
||||
// Process all candidate files in `src` and its subfolders ...
|
||||
include: includeFiles,
|
||||
|
||||
// When calculating the relative path to these files use this as the base path.
|
||||
// So `src/foo/bar.js` will have relative path of `foo/bar.js`
|
||||
basePath: options.sourceDir
|
||||
}
|
||||
];
|
||||
})
|
||||
.config(function(writeFilesProcessor) {
|
||||
// Specify where the writeFilesProcessor will write our generated doc files
|
||||
writeFilesProcessor.outputFolder = options.destDir;
|
||||
});
|
||||
return shredder;
|
||||
}
|
||||
Loading…
Reference in New Issue