cordova-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From dblot...@apache.org
Subject docs commit: Added deployment instructions to README.md. Ported the last relevant Python script to JS. Python is no longer necessary to build the site.
Date Thu, 13 Aug 2015 04:17:39 GMT
Repository: cordova-docs
Updated Branches:
  refs/heads/cordova-website 1a4b2485e -> 230817802


Added deployment instructions to README.md. Ported the last relevant Python script to JS.
Python is no longer necessary to build the site.


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

Branch: refs/heads/cordova-website
Commit: 230817802f5a43bf9163ce63d1fbf6bae4fdf352
Parents: 1a4b248
Author: Dmitry Blotsky <dmitry.blotsky@gmail.com>
Authored: Wed Aug 12 21:17:28 2015 -0700
Committer: Dmitry Blotsky <dmitry.blotsky@gmail.com>
Committed: Wed Aug 12 21:17:28 2015 -0700

----------------------------------------------------------------------
 README.md        |  63 +++++++++++-------------------
 gulpfile.js      |   2 +-
 package.json     |   4 +-
 tools/bin/toc.js | 105 ++++++++++++++++++++++++++++++++++++++++++++++++++
 4 files changed, 131 insertions(+), 43 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/23081780/README.md
----------------------------------------------------------------------
diff --git a/README.md b/README.md
index fa37e63..dcf087b 100644
--- a/README.md
+++ b/README.md
@@ -21,6 +21,10 @@ On Windows, follow these steps:
 1. Run this downloaded file.
     1. Use the following extraction path: `C:\Ruby22DevKit`.
 1. Open `cmd.exe`
+    1. Go to the extraction path:
+
+            cd C:\Ruby22DevKit
+
     1. Run these commands (following any instructions they give):
 
             ruby dk.rb init
@@ -48,32 +52,13 @@ Verify the installation by running:
     node --version
     npm --version
 
-## Python and YAML
-
-On Mac OS X and Linux, Python comes installed. To install the Python package manger, go to
[its page][install_pip] and follow the instructions there.
-
-On Windows follow these steps:
-
-1. Go to [this website][python] and click the "Download Python 2.7.x" button.
-1. Run the downloaded file.
-    1. Use the default installation path (usually `C:\Python27`).
-    1. Make sure to check the options to install Pip, and to add Python to the system PATH
environment variable (a restart of the machine may be required).
-
-***
-
-Verify the installation by running:
-
-    python --version
-    pip --version
-
 ## Dependencies
 
-Once Ruby, Python, and JavaScript are installed, install all dependencies by running:
+Once Ruby and JavaScript are installed, install all dependencies by running:
 
     gem install bundle
     bundle install
     npm install
-    pip install pyyaml
 
 On some systems, administrator privileges may be required for some of the above commands.
 
@@ -91,37 +76,39 @@ To work on the website and see changes live, run:
 
     node_modules/.bin/gulp
 
-That command will start a server and watch the source files, regenerating the site and refreshing
the browser whenever changes are made. To make the regeneration faster, the `includes` and
`excludes` properties in the `_config.yml` file can be edited to only build certain files.
For example, to only build the core website and the latest French docs, edit the properties
to look like this:
+That command will start a server and watch the source files, regenerating the site and refreshing
the browser whenever changes are made. To make the regeneration faster, the `excludes` property
in the `_dev.yml` file can be edited to only build certain files. For example, to only build
the core website and not the docs, edit the properties to look like this:
 
     exclude:
         - static/css-src
         - docs
 
-    include:
-        - docs/fr/edge
-
-**NOTE**: *Please don't commit any dev-specific inclusion/exclusion modifications.*
-
-Troubleshooting
-===============
-
-Ask for help on the IRC channel: #cordova on irc.freenode.net.
-
-
-
-
+**NOTE**: *Please don't commit any dev-specific inclusion/exclusion modifications; keep them
local to your development environment.*
 
+Deploying
+=========
 
+This section requires basic knowledge of SVN. If you do not know how to use SVN, refer to
[this tutorial][svn].
 
+First, inspect `_prod.yml` to check that the correct `baseurl` is used. For pre-production
deployment, it should be some non-empty folder (e.g. `"/use-the-force-luke"`), and for a production
deployment it should be empty (i.e. `""`). To then build the full website, run:
 
+    gulp deploy
 
+A folder called `deploy` will be created, and will contain the whole website. Then, in a
directory *outside* of the `cordova-docs` repository, check out the SVN repository that contains
the currently deployed website by running (committer access required):
 
+    svn checkout https://svn.apache.org/repos/asf/cordova/site cordova-website
 
+Now, copy the `cordova-docs/deploy/` directory to the corresponding directory in SVN (i.e.
something like `cordova-website/public/use-the-force-luke/` for the pre-production deployment,
or just `cordova-website/public/` for the production deployment):
 
+    cp -R cordova-docs/deploy/ cordova-website/public/use-the-force-luke/
 
+Finally, go into the cordova-website directory and commit *all* the changes introduced the
newly copied files. The commit might take a while (upwards of 30min), depending on the number
of files copied.
 
+Troubleshooting
+===============
 
+Ask for help on the IRC channel: #cordova on irc.freenode.net.
 
+***
 
 Writing a Blog Post
 ===================
@@ -231,16 +218,10 @@ _Alternative steps (if post-review tool fails)_
     a. Add the group `cordova`
     a. Click `publish`
 
-
-How to deploy the website
--------------------------
-
-Take the `public` directory, copy it to SVN, and commit it.
-
 [ruby_linux]: https://www.ruby-lang.org/en/documentation/installation/#package-management-systems
 [homebrew]: http://brew.sh/
 [linux_node]: https://nodesource.com/blog/nodejs-v012-iojs-and-the-nodesource-linux-repositories#installing-node-js-v0-12
 [install_ruby]: http://rubyinstaller.org/downloads/
 [nodejs]: https://nodejs.org/
 [install_pip]: https://pip.pypa.io/en/latest/installing.html
-[python]: https://www.python.org/downloads/
+[svn]: http://svnbook.red-bean.com/en/1.7/svn.intro.quickstart.html

http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/23081780/gulpfile.js
----------------------------------------------------------------------
diff --git a/gulpfile.js b/gulpfile.js
index a359ce2..d2bbf3c 100644
--- a/gulpfile.js
+++ b/gulpfile.js
@@ -123,7 +123,7 @@ gulp.task("configs", function (done) {
         .pipe(gulp.dest("."));
     execPiped("node", [bin("gen_languages.js"), DOCS_DIR], LANGUAGES_FILE)
         .pipe(gulp.dest("."));
-    exec("python", [bin("all_toc.py"), DOCS_DIR, DATA_DIR], done);
+    exec("node", [bin("toc.js"), DOCS_DIR, DATA_DIR], done);
 });
 
 gulp.task("styles", function() {

http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/23081780/package.json
----------------------------------------------------------------------
diff --git a/package.json b/package.json
index 91f10e5..6ad9113 100644
--- a/package.json
+++ b/package.json
@@ -28,15 +28,17 @@
     "js-yaml": "^3.2.2",
     "less": "^2.5.1",
     "node-dir": "^0.1.6",
+    "optimist": "^0.6.1",
+    "q": "^1.4.1",
     "shelljs": "^0.3.0",
     "vinyl-buffer": "^1.0.0",
     "vinyl-source-stream": "^1.1.0",
+    "walk": "^2.3.9",
     "yargs": "^1.3.1"
   },
   "devDependencies": {
     "colors": "^1.0.3",
     "diff": "^1.2.0",
-    "js-yaml": "^3.3.1",
     "jshint": "^2.5.8",
     "mocha": "^1.21.4"
   },

http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/23081780/tools/bin/toc.js
----------------------------------------------------------------------
diff --git a/tools/bin/toc.js b/tools/bin/toc.js
new file mode 100644
index 0000000..fb0ce0a
--- /dev/null
+++ b/tools/bin/toc.js
@@ -0,0 +1,105 @@
+// 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 path = require("path");
+var yaml = require("js-yaml");
+var walk = require("walk");
+var Q    = require("q");
+var argv = require("optimist").argv;
+
+var util = require("./util");
+
+function isUnderline(line) {
+    return /-+|=+|\*+/.test(line);
+}
+
+function getPageTitle(pagePath) {
+    return path.basename(pagePath).replace('.md', '');
+}
+
+function generate(sourceDir, prefix) {
+
+    var deferred = Q.defer();
+    var toc      = [];
+
+    var walker = walk.walk(sourceDir);
+
+    walker.on("file", function (root, fileStats, next) {
+        var dirPrefix = root.replace(sourceDir, '');
+        var filePath  = path.join(dirPrefix, fileStats.name);
+        var entry     = {
+            name: getPageTitle(filePath),
+            url:  path.join(prefix, filePath)
+        };
+        toc.push(entry);
+        next();
+    });
+
+    walker.on("errors", function (root, nodeStatsArray, next) {
+        console.error("ERROR while processing " + root);
+        next();
+    });
+
+    walker.on("end", function () {
+        deferred.resolve(toc);
+    });
+
+    return deferred.promise;
+}
+
+function main () {
+
+    var docsRoot = argv._[0];
+    var dataRoot = argv._[1];
+
+    // validate args
+    if ((!docsRoot) || (!dataRoot)) {
+        var scriptName = path.basename(process.argv[1]);
+        console.log("usage: " + scriptName + " docsRoot dataRoot");
+        console.log(scriptName + ": error: too few arguments");
+        return 1;
+    }
+
+    var tocRoot = path.join(dataRoot, 'toc');
+
+    // go through all the languages
+    util.listdirsSync(docsRoot).forEach(function (languageName) {
+
+        var languagePath = path.join(docsRoot, languageName);
+
+        // go through all the versions
+        util.listdirsSync(languagePath).forEach(function (versionName) {
+
+            var versionPath = path.join(languagePath, versionName);
+            var prefix      = "/docs/" + languageName + "/" + versionName;
+            var outputName  = util.generatedTocfileName(languageName, versionName);
+            var outputPath  = path.join(tocRoot, outputName);
+
+            // generate file
+            generate(versionPath, prefix).then(function (toc) {
+                var tocText = yaml.dump(toc);
+                console.log(outputPath);
+                fs.writeFileSync(outputPath, tocText, 'utf-8');
+            });
+        });
+    });
+}
+
+main();


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


Mime
View raw message