From 24948fde5035a19a6ac2c22df10cb444c1cf5c77 Mon Sep 17 00:00:00 2001 From: Jay Traband Date: Sat, 8 Aug 2015 13:55:53 -0700 Subject: [PATCH] added browser-sync, modified shred-single-dir in doc-shredder to return a promise, updated readme. --- README.md | 58 +++++++----- gulpfile.js | 44 ++++++--- package.json | 75 ++++----------- public/doc-shredder/doc-shredder.js | 136 ++++++++++++++++++++++++++++ 4 files changed, 218 insertions(+), 95 deletions(-) create mode 100644 public/doc-shredder/doc-shredder.js diff --git a/README.md b/README.md index aaad762670..83b6c9e370 100644 --- a/README.md +++ b/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只是部署到了 ，但尚未撰写中文的部署指南，不过你可以尝试自行按照英文版的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/) -我们将和官方英文版保持同步翻译，并同步发布到国内镜像 - 。 +## 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`
-特别是： + *or on Windows*
-- **不得去掉**“关于中文版”的入口链接，也不得增删改“关于中文版”页的内容。 -- 如果您是**商业网站（包括但不限于任何有广告或收费的网站）**要发布或转载，请联系我们 和 。 + `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/). diff --git a/gulpfile.js b/gulpfile.js index 0251ed5a73..01435336a0 100644 --- a/gulpfile.js +++ b/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); diff --git a/package.json b/package.json index 3e689a864d..3fa599d421 100644 --- a/package.json +++ b/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 " + ] } diff --git a/public/doc-shredder/doc-shredder.js b/public/doc-shredder/doc-shredder.js new file mode 100644 index 0000000000..77a590270d --- /dev/null +++ b/public/doc-shredder/doc-shredder.js @@ -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; +}