cordova-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From dblot...@apache.org
Subject docs commit: Fixing formatting in docs README. Adding instructions and script for version-bumping docs. Made latest_docs_version come from the VERSION file, through the _version.yml file.
Date Fri, 02 Oct 2015 21:47:36 GMT
Repository: cordova-docs
Updated Branches:
  refs/heads/cordova-website f919e1cde -> 772f3d90e


Fixing formatting in docs README. Adding instructions and script for version-bumping docs.
Made latest_docs_version come from the VERSION file, through the _version.yml file.


Project: http://git-wip-us.apache.org/repos/asf/cordova-docs/repo
Commit: http://git-wip-us.apache.org/repos/asf/cordova-docs/commit/772f3d90
Tree: http://git-wip-us.apache.org/repos/asf/cordova-docs/tree/772f3d90
Diff: http://git-wip-us.apache.org/repos/asf/cordova-docs/diff/772f3d90

Branch: refs/heads/cordova-website
Commit: 772f3d90e7cab3b417c9350420bf9de286440830
Parents: f919e1c
Author: Dmitry Blotsky <dmitry.blotsky@gmail.com>
Authored: Thu Oct 1 20:50:04 2015 -0700
Committer: Dmitry Blotsky <dmitry.blotsky@gmail.com>
Committed: Thu Oct 1 20:50:04 2015 -0700

----------------------------------------------------------------------
 .gitignore                    |   1 +
 _config.yml                   |   2 +-
 doc/README/en/README.md       | 140 ++++++++++++++++----------------
 gulpfile.js                   | 158 +++++++++++++++++++++++--------------
 package.json                  |   4 +
 tools/bin/incrementversion    | 110 --------------------------
 tools/bin/incrementversion.js | 144 +++++++++++++++++++++++++++++++++
 tools/bin/toc.js              |   2 +-
 8 files changed, 317 insertions(+), 244 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/772f3d90/.gitignore
----------------------------------------------------------------------
diff --git a/.gitignore b/.gitignore
index db0161f..f687bf5 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,6 +1,7 @@
 build-*
 *.pyc
 _defaults.yml
+_version.yml
 www/_data/languages.yml
 node_modules
 www/static/css

http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/772f3d90/_config.yml
----------------------------------------------------------------------
diff --git a/_config.yml b/_config.yml
index 146c92f..e7172e0 100644
--- a/_config.yml
+++ b/_config.yml
@@ -12,7 +12,7 @@ repo:
     uri:    https://github.com/apache/cordova-docs
     branch: cordova-website
 
-latest_docs_version: 5.1.1
+latest_docs_version: edge
 
 # NOTE: defaults are configured in _defaults.yml, which is a generated file
 

http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/772f3d90/doc/README/en/README.md
----------------------------------------------------------------------
diff --git a/doc/README/en/README.md b/doc/README/en/README.md
index 529ef31..1e2daad 100644
--- a/doc/README/en/README.md
+++ b/doc/README/en/README.md
@@ -24,49 +24,34 @@ Contributing to the Documentation
 
 ### Report or Fix an Issue
 
-We use [Apache JIRA](https://issues.apache.org/jira/browse/CB)
-
-By the way, you rock! Thanks for helping us improve the documentation!
+We use [Apache JIRA](https://issues.apache.org/jira/browse/CB). By the way, you rock! Thanks
for helping us improve the documentation!
 
 ### Using Git
 
-Are you new to Git or contributing on GitHub?
-
-We have [written a few Git tutorials](http://wiki.apache.org/cordova/ContributorWorkflow)
-to help you get started with contributing to the documentation.
+Are you new to Git or contributing on GitHub? We have [written a few Git tutorials](http://wiki.apache.org/cordova/ContributorWorkflow)
to help you get started with contributing to the documentation.
 
 ### Sending Pull Requests
 
-Pull requests are welcome!
-
-We appreciate the use of topic branches.
+Pull requests are welcome! We appreciate the use of topic branches.
 
     git checkout -b issue_23
 
-    # code
+    # do some coding ...
 
     git commit -m "Issue 23: Fix a bad bug."
-
     git push origin issue_23
 
     # send pull request from branch issue_23 to cordova:master
 
 ### Adding a Language
 
-Do you want the Apache Cordova documentation in another language? We do too!
-With the support of [Crowdin](http://crowdin.net/project/cordova),
-a translation and localization management platform, translators can login to
-the easy-to-use tooling and provide as much or as little translation assistance as
-they would like. If you know another language please support Cordova and contribute.
-http://crowdin.net/project/cordova. For some best practices for using the
-Crowdin tool please see our wiki http://wiki.apache.org/cordova/CordovaTranslations.
+Do you want the Apache Cordova documentation in another language? We do too! With the support
of [Crowdin](http://crowdin.net/project/cordova), a translation and localization management
platform, translators can login to the easy-to-use tooling and provide as much or as little
translation assistance as they would like. If you know another language please support Cordova
and contribute. http://crowdin.net/project/cordova. For some best practices for using the
Crowdin tool please see our wiki http://wiki.apache.org/cordova/CordovaTranslations.
 
 Cordova language administrators, don't forget these steps:
 
 __1. config.json__
 
-For each language and version, there is a `config.json` that defines the name of the language
and
-how to merge the files.
+For each language and version, there is a `config.json` that defines the name of the language
and how to merge the files.
 
 __2. Customizing HTML template__
 
@@ -97,6 +82,7 @@ Right now documentation could be run using Node.js either on Windows, or
on Linu
 4. Install dependencies. In the root of the cloned cordova-docs folder run
 
         npm install
+
 5. Now you able to build documentation locally.
 
 ### Quick Preview
@@ -105,19 +91,30 @@ When making minor edits, it is usually safe to simply render the edited
from
 Markdown to HTML. Many code editors have plugins to render Markdown to HTML
 and there are a handful of [good](http://dillinger.io/) online editors.
 
-Currently, a Node.JS script and [joDoc-js](https://github.com/kant2002/jodoc-js) are
-used to generate the HTML documentation.
+Currently, a Node.JS script and [joDoc-js](https://github.com/kant2002/jodoc-js) are used
to generate the HTML documentation.
 
 Generating a Version Release
----------------------------
+----------------------------
+
+To increment the documentation version (e.g. `X.X.X`, either use the gulp task:
 
-There is a Rake task to increment the version, generate the version directory, and update
the edge documentation.
+    gulp newversion --version X.X.X
 
-    # generate version 4.1.0 for english.
-    .\bin\incrementversion en 4.1.0
+or manually run the `incrementversion.js` script:
+
+    node ./tools/bin/incrementversion.js www/docs X.X.X
+
+To only run for a specific language (__this should only happen when translation is intentionally
left out for a given version__), specify the language to the Gulp task as follows:
+
+    gulp newversion --version X.X.X --language YY
+
+or manually, to the script, as follows:
+
+    node ./tools/bin/incrementversion.js www/docs X.X.X YY
 
 QA for docs & translation
----------------------------
+-------------------------
+
 In order to maintain quality of documentation and translation, following tools could be used.
 
 1. `fixyaml` tool.
@@ -125,9 +122,8 @@ In order to maintain quality of documentation and translation, following
tools c
 3. `validatejsdoc` tool.
 
 ### FixYaml tool.
-The tool `fixyaml` created to automatically fix YAML headers in the translation files after
-exporting translated content from CrowdIn. Sometimes Crowdin messup with Apache license headers
-and this tool created to fix that.
+
+The tool `fixyaml` created to automatically fix YAML headers in the translation files after
exporting translated content from CrowdIn. Sometimes Crowdin messup with Apache license headers
and this tool created to fix that.
 
 Usage:
 
@@ -137,7 +133,9 @@ Usage:
     bin\fixyaml ru 5.0.0    # Runs fixyaml on the version 5.0.0 of Russian docs.
 
 ### Translation Report tool.
+
 The tool `translationreport` currently provide two QA checks for translation.
+
 1. It verifies that autolinking works after translation, and that translated text point to
the same pages as
 in the original documentation.
 2. It verifies that translated and original files create same DOM structure, since after
exporting from
@@ -145,88 +143,83 @@ Crowdin, the markdown files could contain unnescessary lines, which
lead to brok
 not needed code sections for example.
 
 ### Validate JSDoc tool.
-The tool `validatejsdoc` allow verification of the current implementation of JSDoc with reference
implementation.
-It was used during porting JSDoc to the Node version of JSDoc, and now currently not used
in the workflow.
+
+The tool `validatejsdoc` allow verification of the current implementation of JSDoc with reference
implementation. It was used during porting JSDoc to the Node version of JSDoc, and now currently
not used in the workflow.
 
 Recommendations for the translators
--------------------------
-If you intend to create quality translation of the Cordova docs, please not only
-work in Crowdin and translate documentation, but also please go extra mile and verify that
-generated documentation for your language is also produce quality results.
+-----------------------------------
+
+If you intend to create quality translation of the Cordova docs, please not only work in
Crowdin and translate documentation, but also please go extra mile and verify that generated
documentation for your language is also produce quality results.
 
 For that you should have Crowdin CLI tool. You could
+
 1. take it from [here](https://crowdin.com/page/cli-tool)
 2. or install alternate NodeJS client
 
     `npm -g install crowdin-cli`
 
-You will use that tool for the downloading translation from Crowdin.
-To be able to download translated content from the Crowdin you should have API key for the
project.
-Please ask for it on the mailing list.
+You will use that tool for the downloading translation from Crowdin. To be able to download
translated content from the Crowdin you should have API key for the project. Please ask for
it on the mailing list.
 
 After you receive access to API key, create `crowdin.yaml` coniguration file, as described
in the [CrowdIn cli tool page](https://crowdin.com/page/cli-tool).
 
-Now you ready to download content from CrowdIn.
-Run following commands (All commands here would be for NodeJS version of Crowdin CLI)
+Now you ready to download content from CrowdIn. Run following commands (All commands here
would be for NodeJS version of Crowdin CLI)
 
 1. Prepare translated content for downloading.
 
-   `crowdin-cli export`
+        crowdin-cli export
+
+    This command collect latest translations and made them available for downloading. Without
that command, the translation which you would download would be stalled.
+
+    Be careful with this command, since Crowdin implement throttling and allow you export
content not faster then 1 time in 30 minutes, or so.
 
-   This command collect latest translations and made them available for downloading. Without
that command, the translation which you would download would be stalled.
-   Be careful with this command, since Crowdin implement throttling and allow you export
content not faster then 1 time in 30 minutes, or so.
 2. Download content for you language. I will use Russian as example.
 
-   `crowdin-cli download -l ru -o ru.zip`
+        crowdin-cli download -l ru -o ru.zip
 
-   This command download all translations for Russian language to the `ru.zip` file.
+    This command download all translations for Russian language to the `ru.zip` file.
 
 3. Now unpack the download content to the temporary directory.
 
-   `unzip -x ru.zip -d tmp/ru`
+        unzip -x ru.zip -d tmp/ru
 
 4. Copy the unpacked content to the `docs` folder.
+    * on Linux:
 
-   a) on Linux:
-    `cp tmp/ru/cordova-docs/docs/ru/edge/* docs/ru/edge/`
+            cp tmp/ru/cordova-docs/docs/ru/edge/* docs/ru/edge/
 
-   b) on Windows:
-    `xcopy tmp/ru/cordova-docs/docs/ru/edge/* docs/ru/edge/`
+    * on Windows:
 
-5. Remove temporary directory. In my case `tmp/ru`.
+            xcopy tmp/ru/cordova-docs/docs/ru/edge/* docs/ru/edge/
 
-   Now you have fresh translation and could generate content.
+5. Remove temporary directory. In my case `tmp/ru`. Now you have fresh translation and could
generate content.
 
 6. Fix Yaml headers by running.
 
-   `bin/fixyaml ru edge`
+        bin/fixyaml ru edge
 
 7. Run generator. You should generate both English version and language which you tranlate.
 
-   ```
-   bin/genjs en edge
-   bin/genjs ru edge
-   ```
+        bin/genjs en edge
+        bin/genjs ru edge
 
-   The generated documentation contains in the `public/en/edge` and `public/ru/edge`
+    The generated documentation contains in the `public/en/edge` and `public/ru/edge`
 
-   You need both versions, to validate that translated docs would have same structure as
original documentation.
+    You need both versions, to validate that translated docs would have same structure as
original documentation.
 
 8. Validate you translation.
 
-   `bin/translationreport ru edge`
+        bin/translationreport ru edge
+
+    This will give you list of files which has structural differences from the original docs.
+    Below the example output:
 
-   This will give you list of files which has structural differences from the original docs.
-   Below the example output:
-   ```
-    => Validating translation for version edge on language ru...
-   Comparing C:\Users\kant\Documents\GitHub\cordova-docs\public\en\edge
-   with C:\Users\kant\Documents\GitHub\cordova-docs\public\ru\edge
-   Path guide_platforms_blackberry10_upgrade.md.html is different.
-   Path guide_platforms_blackberry_upgrade.md.html is different.
-   Path guide_platforms_ios_tools.md.html is different.
-   Path guide_support_index.md.html is different.
-   ```
+        => Validating translation for version edge on language ru...
+        Comparing C:\Users\kant\Documents\GitHub\cordova-docs\public\en\edge
+        with C:\Users\kant\Documents\GitHub\cordova-docs\public\ru\edge
+        Path guide_platforms_blackberry10_upgrade.md.html is different.
+        Path guide_platforms_blackberry_upgrade.md.html is different.
+        Path guide_platforms_ios_tools.md.html is different.
+        Path guide_support_index.md.html is different.
 
 9. Now you could open pregenerated files and compare the English version with your translated
versions.
     Open both versions and find out what's wrong.
@@ -243,6 +236,7 @@ Run following commands (All commands here would be for NodeJS version
of Crowdin
     b. The broken HTML structure.
 
 11. Let's fix first type of errors - Missing/Additional links.
+
     To fix these type of errors you have to make sure that text in your translation where
you want to have link,
     match exactly the header in the translated document, otherwise auto-linking would not
work.
     You have to rephrase the sentences to fix that.

http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/772f3d90/gulpfile.js
----------------------------------------------------------------------
diff --git a/gulpfile.js b/gulpfile.js
index fec03d1..e08d65b 100644
--- a/gulpfile.js
+++ b/gulpfile.js
@@ -10,57 +10,62 @@ var gutil       = require("gulp-util");
 var less        = require("gulp-less");
 var sass        = require("gulp-sass");
 var replace     = require("gulp-replace");
+var header      = require("gulp-header");
+var footer      = require("gulp-footer");
+var rename      = require("gulp-rename");
+var browsersync = require("browser-sync");
 var vstream     = require("vinyl-source-stream");
 var buffer      = require("vinyl-buffer");
-var browsersync = require("browser-sync");
-var header      = require("gulp-header");
 
 var browserify = require("browserify");
 var reactify   = require("reactify");
 var uglify     = require("gulp-uglify");
 var envify     = require("envify");
-var htmllint   = require('gulp-htmllint');
-var crawler    = require('simplecrawler');
+var htmllint   = require("gulp-htmllint");
+var crawler    = require("simplecrawler");
 
 // constants
-var CONFIG_FILES = ["_config.yml", "_defaults.yml"];
-var DEV_FLAGS    = ["--config", CONFIG_FILES.concat(["_dev.yml"]).join(","), "--trace"];
-var PROD_FLAGS   = ["--config", CONFIG_FILES.concat(["_prod.yml"]).join(",")];
-
-var YAML_FRONT_MATTER = "---\n---\n";
-var WATCH_INTERVAL    = 1000; // in milliseconds
-
 var ROOT_DIR   = ".";
 var SOURCE_DIR = path.join(ROOT_DIR, "www");
 var DEV_DIR    = path.join(ROOT_DIR, "build-dev");
 var PROD_DIR   = path.join(ROOT_DIR, "build-prod");
-var BASE_URL   = "/use-the-force-luke";
-
-var DATA_DIR         = path.join(SOURCE_DIR, "_data");
-var DOCS_DIR         = path.join(SOURCE_DIR, "docs");
-var CSS_SRC_DIR      = path.join(SOURCE_DIR, "static", "css-src");
-var CSS_OUT_DIR      = path.join(SOURCE_DIR, "static", "css");
-var PLUGINS_SRC_DIR  = path.join(SOURCE_DIR, "static", "plugins");
-var JS_DIR           = path.join(SOURCE_DIR, "static", "js");
-var BIN_DIR          = path.join(ROOT_DIR, "tools", "bin");
-
-var CONFIG_FILE       = path.join(ROOT_DIR, "_config.yml");
-var DEFAULTS_FILE     = path.join(ROOT_DIR, "_defaults.yml");
+
+var DATA_DIR        = path.join(SOURCE_DIR, "_data");
+var TOC_DIR         = path.join(DATA_DIR, "toc");
+var DOCS_DIR        = path.join(SOURCE_DIR, "docs");
+var CSS_SRC_DIR     = path.join(SOURCE_DIR, "static", "css-src");
+var CSS_OUT_DIR     = path.join(SOURCE_DIR, "static", "css");
+var PLUGINS_SRC_DIR = path.join(SOURCE_DIR, "static", "plugins");
+var JS_DIR          = path.join(SOURCE_DIR, "static", "js");
+var BIN_DIR         = path.join(ROOT_DIR, "tools", "bin");
+
+var CONFIG_FILE          = "_config.yml";
+var DEFAULTS_CONFIG_FILE = "_defaults.yml";
+var VERSION_CONFIG_FILE  = "_version.yml";
+var PROD_CONFIG_FILE     = "_prod.yml";
+var DEV_CONFIG_FILE      = "_dev.yml";
+
+var VERSION_FILE      = "VERSION";
 var LANGUAGES_FILE    = path.join(DATA_DIR, "languages.yml");
 var PLUGINS_FILE_NAME = "plugins.js";
 var PLUGINS_FILE      = path.join(JS_DIR, PLUGINS_FILE_NAME);
 var PLUGINS_SRC_FILE  = path.join(PLUGINS_SRC_DIR, "app.js");
 
-// global variables
-var prod = false;
+var CONFIG_FILES = [CONFIG_FILE, DEFAULTS_CONFIG_FILE, VERSION_CONFIG_FILE];
+var DEV_FLAGS    = ["--config", CONFIG_FILES.concat([DEV_CONFIG_FILE]).join(","), "--trace"];
+var PROD_FLAGS   = ["--config", CONFIG_FILES.concat([PROD_CONFIG_FILE]).join(",")];
 
-// passed options
-if (gutil.env.prod) {
-    prod = true;
-}
+var BASE_URL          = "/use-the-force-luke";
+var YAML_FRONT_MATTER = "---\n---\n";
+var WATCH_INTERVAL    = 1000; // in milliseconds
+var VERSION_VAR_NAME  = "latest_docs_version";
+
+var PROD_BY_DEFAULT = false;
 
-// computed variables
-var out_dir = prod ? PROD_DIR : DEV_DIR;
+// compute/get/set/adjust passed options
+gutil.env.prod   = gutil.env.prod || PROD_BY_DEFAULT;
+gutil.env.dev    = !gutil.env.prod;
+gutil.env.outDir = gutil.env.prod ? PROD_DIR : DEV_DIR;
 
 // helpers
 function execPiped(command, args, fileName) {
@@ -85,15 +90,15 @@ function remove(path) {
 }
 
 function getJekyllExecutable() {
-    if (process.platform === 'win32') {
-        return 'jekyll.bat';
+    if (process.platform === "win32") {
+        return "jekyll.bat";
     } else {
-        return 'jekyll';
+        return "jekyll";
     }
 }
 
 function jekyllBuild(done) {
-    var flags  = prod ? PROD_FLAGS : DEV_FLAGS;
+    var flags  = gutil.env.prod ? PROD_FLAGS : DEV_FLAGS;
     var jekyll = getJekyllExecutable();
     exec(jekyll, ["build"].concat(flags), done);
 }
@@ -139,14 +144,14 @@ gulp.task("watch", ["serve"], function () {
 
 gulp.task("serve", ["build"], function () {
     var route = {};
-    if(prod) {
-        route[BASE_URL] = out_dir;
+    if(gutil.env.prod) {
+        route[BASE_URL] = gutil.env.outDir;
     }
 
     browsersync({
         notify: true,
         server: {
-            baseDir: out_dir,
+            baseDir: gutil.env.outDir,
             routes: route
         }
     });
@@ -173,8 +178,20 @@ gulp.task("languages", function () {
         .pipe(gulp.dest(ROOT_DIR));
 });
 
+gulp.task("version", function () {
+    // this code is stupid; it's basically the line:
+    //      cat VERSION | sed -e 's/^/latest_docs_version: /' > _version.yml
+    // however we're in Gulp, and on Windows... so we contort it into a monster
+    return gulp
+        .src(VERSION_FILE)
+        .pipe(header(VERSION_VAR_NAME + ": "))
+        .pipe(footer("\n"))
+        .pipe(rename(VERSION_CONFIG_FILE))
+        .pipe(gulp.dest("."));
+});
+
 gulp.task("defaults", function () {
-    return execPiped("node", [bin("gen_defaults.js"), DOCS_DIR], DEFAULTS_FILE)
+    return execPiped("node", [bin("gen_defaults.js"), DOCS_DIR], DEFAULTS_CONFIG_FILE)
         .pipe(gulp.dest(ROOT_DIR));
 });
 
@@ -188,7 +205,7 @@ gulp.task("less", function () {
         .pipe(less())
         .pipe(header(YAML_FRONT_MATTER))
         .pipe(gulp.dest(CSS_OUT_DIR))
-        .pipe(gulp.dest(CSS_OUT_DIR.replace(SOURCE_DIR, out_dir)))
+        .pipe(gulp.dest(CSS_OUT_DIR.replace(SOURCE_DIR, gutil.env.outDir)))
         .pipe(browsersync.reload({stream: true}));
 })
 
@@ -197,7 +214,7 @@ gulp.task("css", function () {
         .src(path.join(CSS_SRC_DIR, "**", "*.css"))
         .pipe(header(YAML_FRONT_MATTER))
         .pipe(gulp.dest(CSS_OUT_DIR))
-        .pipe(gulp.dest(CSS_OUT_DIR.replace(SOURCE_DIR, out_dir)))
+        .pipe(gulp.dest(CSS_OUT_DIR.replace(SOURCE_DIR, gutil.env.outDir)))
         .pipe(browsersync.reload({stream: true}));
 })
 
@@ -207,16 +224,16 @@ gulp.task("sass", function() {
         .pipe(sass().on("error", sass.logError))
         .pipe(header(YAML_FRONT_MATTER))
         .pipe(gulp.dest(CSS_OUT_DIR))
-        .pipe(gulp.dest(CSS_OUT_DIR.replace(SOURCE_DIR, out_dir)))
+        .pipe(gulp.dest(CSS_OUT_DIR.replace(SOURCE_DIR, gutil.env.outDir)))
         .pipe(browsersync.reload({stream: true}));
 });
 
 gulp.task("plugins", function() {
-    if (prod) {
+    if (gutil.env.prod) {
         process.env.NODE_ENV = "production";
     }
 
-    var stream = browserify(PLUGINS_SRC_FILE, {debug: !prod})
+    var stream = browserify(PLUGINS_SRC_FILE, {debug: !gutil.env.prod})
         .transform(reactify)
         .transform(envify)
         .bundle()
@@ -224,14 +241,14 @@ gulp.task("plugins", function() {
         .pipe(vstream(PLUGINS_FILE_NAME))
         .pipe(buffer());
 
-    if (prod) {
+    if (gutil.env.prod) {
         stream = stream
             .pipe(uglify())
             .on("error", gutil.log);
     }
 
     return stream
-        .pipe(gulp.dest(JS_DIR.replace(SOURCE_DIR, out_dir)))
+        .pipe(gulp.dest(JS_DIR.replace(SOURCE_DIR, gutil.env.outDir)))
         .pipe(browsersync.reload({stream: true}))
         // NOTE:
         //      adding YAML front matter at the end
@@ -246,7 +263,7 @@ gulp.task("plugins", function() {
 });
 
 // compound tasks
-gulp.task("configs", ["languages", "defaults"]);
+gulp.task("configs", ["languages", "defaults", "version"]);
 gulp.task("styles", ["less", "css", "sass"]);
 gulp.task("build", ["gen-full"]);
 gulp.task("default", ["watch"]);
@@ -256,21 +273,43 @@ gulp.task("link-bugs", function (done) {
     exec(bin("linkify-bugs.sh"), [path.join(SOURCE_DIR, "_posts")], done);
 });
 
-gulp.task('lint', function() {
+gulp.task("lint", function() {
     return gulp.src(path.join("./", "**", "*.html"))
         .pipe(htmllint());
 });
 
-gulp.task('checklinks', function(cb) {
-  crawler.crawl('http://localhost:3000/')
-    .on('fetch404', function(queueItem, response) {
-      gutil.log('Resource not found linked from ' +
-                      queueItem.referrer + ' to', queueItem.url);
-      gutil.log('Status code: ' + response.statusCode);
-    })
-    .on('complete', function(queueItem) {
-      cb();
-    });
+gulp.task("newversion", function(done) {
+
+    if (!gutil.env.version) {
+        gutil.log(gutil.colors.red("No version given."));
+        gutil.log("Specify new version with '--version X.X.X'.");
+        gutil.log("(Optionally) Specify language with '--language YY'.");
+        done();
+        return;
+    }
+
+    var args = [bin("incrementversion.js"), DOCS_DIR, TOC_DIR, gutil.env.version];
+
+    if (gutil.env.language) {
+        args.push(gutil.env.language);
+    }
+
+    exec("node", args, done);
+});
+
+gulp.task("checklinks", function(done) {
+    crawler
+        .crawl("http://localhost:3000/")
+        .on("fetch404", function(queueItem, response) {
+            gutil.log(
+                "Resource not found linked from " +
+                queueItem.referrer + " to", queueItem.url
+            );
+            gutil.log("Status code: " + response.statusCode);
+        })
+        .on("complete", function(queueItem) {
+            done();
+        });
 });
 
 gulp.task("clean", function () {
@@ -280,5 +319,6 @@ gulp.task("clean", function () {
     remove(CSS_OUT_DIR);
     remove(PLUGINS_FILE);
     remove(LANGUAGES_FILE);
-    remove(DEFAULTS_FILE);
+    remove(DEFAULTS_CONFIG_FILE);
+    remove(VERSION_CONFIG_FILE);
 });

http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/772f3d90/package.json
----------------------------------------------------------------------
diff --git a/package.json b/package.json
index 9c8c8bd..11aa94f 100644
--- a/package.json
+++ b/package.json
@@ -24,8 +24,10 @@
     "fs-extra": "^0.11.1",
     "gulp": "^3.9.0",
     "gulp-concat": "^2.6.0",
+    "gulp-footer": "^1.0.5",
     "gulp-header": "1.2.2",
     "gulp-less": "^3.0.3",
+    "gulp-rename": "^1.2.2",
     "gulp-replace": "^0.5.4",
     "gulp-run": "^1.6.8",
     "gulp-sass": "^2.0.4",
@@ -34,12 +36,14 @@
     "jodoc": "git://github.com/kant2002/jodoc-js",
     "js-yaml": "^3.2.2",
     "less": "^2.5.1",
+    "ncp": "^2.0.0",
     "node-dir": "^0.1.6",
     "optimist": "^0.6.1",
     "q": "^1.4.1",
     "react": "^0.13.3",
     "react-tools": "^0.13.3",
     "reactify": "^1.1.1",
+    "semver": "^5.0.3",
     "shelljs": "^0.3.0",
     "vinyl-buffer": "^1.0.0",
     "vinyl-source-stream": "^1.1.0",

http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/772f3d90/tools/bin/incrementversion
----------------------------------------------------------------------
diff --git a/tools/bin/incrementversion b/tools/bin/incrementversion
deleted file mode 100755
index e74852f..0000000
--- a/tools/bin/incrementversion
+++ /dev/null
@@ -1,110 +0,0 @@
-#!/usr/bin/env node
-/*
-       Licensed to the Apache Software Foundation (ASF) under one
-       or more contributor license agreements.  See the NOTICE file
-       distributed with this work for additional information
-       regarding copyright ownership.  The ASF licenses this file
-       to you under the Apache License, Version 2.0 (the
-       "License"); you may not use this file except in compliance
-       with the License.  You may obtain a copy of the License at
-
-         http://www.apache.org/licenses/LICENSE-2.0
-
-       Unless required by applicable law or agreed to in writing,
-       software distributed under the License is distributed on an
-       "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
-       KIND, either express or implied.  See the License for the
-       specific language governing permissions and limitations
-       under the License.
-*/
-/*jslint node:true, nomen: true */
-
-var fs = require('fs-extra'),
-    path = require('path'),
-    yargs = require('yargs')
-    .describe('edge', 'Compare edge version of English docs with Ruby version')
-    .count("verbose")
-    .alias('v', 'verbose')
-    .describe('verbose', 'Increase verbosity level of produced output')
-    .demand(2)
-    .usage('Usage: $0 [lang] [version]\n' +
-        '    <lang>: Language for which update version number.\n' +
-        '    <version>: Next version.\n');
-var argv = yargs.argv;
-
-function processEachFile(source_path, callback) {
-    var directoryEntries = fs.readdirSync(source_path);
-    directoryEntries.forEach(function (dirEntry) {
-        var fullPath = path.join(source_path, dirEntry),
-            stat;
-        if (!fs.existsSync(fullPath)) {
-            return;
-        }
-
-        stat = fs.lstatSync(fullPath);
-        if (stat.isFile()) {
-            callback(fullPath);
-            return;
-        }
-
-        if (stat.isDirectory()) {
-            processEachFile(fullPath, callback);
-            return;
-        }
-    });
-}
-
-if (argv.help) {
-    yargs.showHelp();
-    process.exit(1);
-}
-
-var language = null,
-    version = null,
-    argumentsCount = argv._.length;
-if (argumentsCount === 2) {
-    language = argv._[0];
-    version = argv._[1];
-} else {
-    yargs.showHelp();
-    process.exit(1);
-}
-
-var prevVersion = fs.readFileSync('VERSION', { encoding: 'utf8' }),
-    edge_dir = path.join('docs', language, 'edge'),
-    release_dir = path.join('docs', language, version),
-    versionShort;
-
-prevVersion = prevVersion.replace(/rc\d+$/, '').trim();
-
-if (argv.verbose > 0) {
-    console.log("Copy edge docs to " + release_dir);
-}
-
-fs.mkdirSync(release_dir);
-fs.copySync(edge_dir, release_dir);
-
-versionShort = version.replace(/rc\d+$/, '').trim();
-if (prevVersion !== versionShort) {
-    // Replace x.x.x to new version in all files.
-    processEachFile(release_dir, function (filename) {
-        if (path.extname(filename) != ".md" && path.extname(filename) != ".html")
{
-            return;
-        }
-        
-        var content = fs.readFileSync(filename, { encoding: 'utf8' });
-        content.replace('x.x.x', versionShort);
-        fs.writeFileSync(filename, content);
-    });
-}
-
-// Save version number to file.
-fs.writeFileSync('VERSION', version);
-
-console.log("Generated version " + version);
-console.log("");
-console.log("Next steps:");
-console.log("  1. Review the update using `git status`");
-console.log("  2. Commit the changes as 'Version " + version + "'");
-console.log("  3. Tag the commit as '" + version + "'");
-console.log("");
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/772f3d90/tools/bin/incrementversion.js
----------------------------------------------------------------------
diff --git a/tools/bin/incrementversion.js b/tools/bin/incrementversion.js
new file mode 100755
index 0000000..1a0d6e4
--- /dev/null
+++ b/tools/bin/incrementversion.js
@@ -0,0 +1,144 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+"use strict";
+
+var fs     = require("fs");
+var fse    = require("fs-extra");
+var path   = require("path");
+var argv   = require("optimist").argv;
+var semver = require("semver");
+var ncp    = require("ncp");
+
+var util = require("./util");
+
+// constants
+var VERSION_FILE_NAME = "VERSION";
+var DEV_VERSION_NAME  = "edge";
+var ENCODING          = "utf8";
+
+// helpers
+function isValidVersion(version) {
+    if (version == DEV_VERSION_NAME) {
+        return false;
+    }
+    if (!semver.valid(version)) {
+        return false;
+    }
+    return true;
+}
+
+function main () {
+
+    // get args
+    var docsRoot   = argv._[0];
+    var tocRoot    = argv._[1];
+    var newVersion = argv._[2];
+    var language   = argv._[3];
+
+    // validate args
+    if (!docsRoot || !newVersion) {
+        console.log("usage: docsRoot tocRoot newVersion [language]");
+        return 1;
+    }
+
+    // get current version
+    var oldVersion = fs.readFileSync(VERSION_FILE_NAME, ENCODING).trim();
+
+    // sanity warning if old version is invalid
+    if (!isValidVersion(oldVersion)) {
+        console.warn("the current version in " + VERSION_FILE_NAME + " is not valid according
to semver!");
+    }
+
+    // validate new version
+    if (!isValidVersion(newVersion)) {
+        console.error(newVersion + " is not a valid version");
+        return 1;
+    }
+
+    // only create greater versions
+    if (!semver.gt(newVersion, oldVersion)) {
+        console.error(newVersion + " is not greater than " + oldVersion);
+        return 1;
+    }
+
+    if (language) {
+        console.log(oldVersion + " -> " + newVersion + " ONLY for " + language);
+    } else {
+        console.log(oldVersion + " -> " + newVersion + " for ALL languages");
+    }
+
+    // update the version file
+    // NOTE:
+    //      no newline is written at the end of the file
+    fs.writeFileSync(VERSION_FILE_NAME, newVersion, ENCODING);
+
+    // get languages to process
+    if (language) {
+        var languageNames = [language];
+    } else {
+        var languageNames = util.listdirsSync(docsRoot);
+    }
+
+    // go through all the languages
+    languageNames.forEach(function (languageName) {
+
+        // get the path to the dev version
+        var devVersionPath = path.join(docsRoot, languageName, DEV_VERSION_NAME);
+        var newVersionPath = path.join(docsRoot, languageName, newVersion);
+
+        // get ToC file paths
+        var devTocfile     = util.manualTocfileName(languageName, DEV_VERSION_NAME);
+        var newTocfile     = util.manualTocfileName(languageName, newVersion);
+        var devTocfilePath = path.join(tocRoot, devTocfile);
+        var newTocfilePath = path.join(tocRoot, newTocfile);
+
+        // check if it exists
+        if (!fs.existsSync(devVersionPath)) {
+            console.error("skipping language " + languageName + " because its " + DEV_VERSION_NAME
+ " version can't be found");
+            return;
+        }
+
+        // sanity check: new version shouldn't exist yet
+        if (fs.existsSync(newVersionPath)) {
+            console.error(newVersionPath + " already exists!");
+            return;
+        }
+
+        // copy the dev version to the new version path
+        ncp.ncp(devVersionPath, newVersionPath, {stopOnErr: true}, function (error) {
+            if (error) {
+                return console.error(error);
+            }
+            console.log(newVersionPath + " created");
+        });
+
+        // if there is a manual ToC file for the dev version, create one for the new version
+        if (fs.existsSync(devTocfilePath)) {
+            var devToc = fs.readFileSync(devTocfilePath, ENCODING);
+            var newToc = devToc.replace("/" + DEV_VERSION_NAME + "/", newVersion)
+            fs.writeFile(newTocfilePath, newToc, ENCODING, function (error) {
+                if (error) {
+                    return console.error(error);
+                }
+                console.log(newTocfilePath + " created");
+            });
+        }
+    });
+}
+
+main();

http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/772f3d90/tools/bin/toc.js
----------------------------------------------------------------------
diff --git a/tools/bin/toc.js b/tools/bin/toc.js
index 71868ce..c09542c 100644
--- a/tools/bin/toc.js
+++ b/tools/bin/toc.js
@@ -117,7 +117,7 @@ function main () {
 
                 var tocText = yaml.dump(toc);
                 console.log(outputPath);
-                fs.writeFileSync(outputPath, tocText, 'utf-8');
+                fs.writeFileSync(outputPath, tocText, 'utf8');
             });
         });
     });


---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@cordova.apache.org
For additional commands, e-mail: commits-help@cordova.apache.org


Mime
View raw message