Mailing-List: contact commits-help@cordova.apache.org; run by ezmlm
Precedence: bulk
Content-Type: text/plain; charset="us-ascii"
MIME-Version: 1.0
Content-Transfer-Encoding: 7bit
From: dblotsky@apache.org
To: commits@cordova.apache.org
Message-Id: <e3b5c38228194c8688c85311c7663592@git.apache.org>
Subject: docs commit: Adding Makefile. Adding --nodocs flag to gulpfile to
 handle generation without docs. Fixing up README.
Date: Fri,  6 Nov 2015 21:08:19 +0000 (UTC)

Repository: cordova-docs
Updated Branches:
  refs/heads/master 366718c18 -> b0e35dad5


Adding Makefile. Adding --nodocs flag to gulpfile to handle generation without docs. Fixing up README.


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

Branch: refs/heads/master
Commit: b0e35dad581b14b622d9774af38685b5cd3ffe05
Parents: 366718c
Author: Dmitry Blotsky <dmitry.blotsky@gmail.com>
Authored: Wed Nov 4 21:24:06 2015 -0800
Committer: Dmitry Blotsky <dmitry.blotsky@gmail.com>
Committed: Fri Nov 6 13:06:42 2015 -0800

----------------------------------------------------------------------
 Makefile     | 175 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 README.md    |  69 +++++++++++----------
 _dev.yml     |   2 +
 _nodocs.yml  |   4 ++
 gulpfile.js  |  39 +++++++++---
 package.json |   2 +
 6 files changed, 254 insertions(+), 37 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/b0e35dad/Makefile
----------------------------------------------------------------------
diff --git a/Makefile b/Makefile
new file mode 100644
index 0000000..8271bc0
--- /dev/null
+++ b/Makefile
@@ -0,0 +1,175 @@
+# Function Reference:
+# 	https://www.gnu.org/software/make/manual/html_node/Text-Functions.html
+#  	https://www.gnu.org/software/make/manual/html_node/File-Name-Functions.html
+# Variable Reference:
+# 	https://www.gnu.org/software/make/manual/html_node/Automatic-Variables.html
+
+# constants
+EMPTY =
+SPACE = $(EMPTY) $(EMPTY)
+COMMA = ,
+
+VERSION_VAR_NAME = latest_docs_version
+
+# paths and files
+BIN_DIR      = tools/bin
+NODE_BIN_DIR = ./node_modules/.bin
+
+SRC_DIR  = www
+DEV_DIR  = build-dev
+PROD_DIR = build-prod
+
+DOCS_DIR         = $(SRC_DIR)/docs
+DATA_DIR         = $(SRC_DIR)/_data
+TOC_DIR          = $(DATA_DIR)/toc
+STATIC_DIR       = $(SRC_DIR)/static
+CSS_SRC_DIR      = $(STATIC_DIR)/css-src
+CSS_DEST_DIR     = $(STATIC_DIR)/css
+PLUGINS_SRC_DIR  = $(STATIC_DIR)/plugins
+PLUGINS_DEST_DIR = $(STATIC_DIR)/js
+
+# executables
+NODE       = node
+GULP       = $(NODE_BIN_DIR)/gulp
+LESSC      = $(NODE_BIN_DIR)/lessc
+SASSC      = $(NODE_BIN_DIR)/node-sass
+BROWSERIFY = $(NODE_BIN_DIR)/browserify
+UGLIFY     = $(NODE_BIN_DIR)/uglifyjs
+
+JEKYLL = jekyll
+# JEKYLL = jekyll.bat
+
+# existing files
+MAIN_CONFIG         = _config.yml
+DEV_CONFIG          = _dev.yml
+PROD_CONFIG         = _prod.yml
+DOCS_EXCLUDE_CONFIG = _nodocs.yml
+PLUGINS_SRC         = $(PLUGINS_SRC_DIR)/app.js
+
+# NOTE:
+#      the .scss files are separate because they combine into MAIN_STYLE_FILE,
+#      which names them on its own, and the SCSS compiler takes care of them
+SCSS_SRC   = $(shell find $(CSS_SRC_DIR) -name "*.scss")
+STYLES_SRC = $(shell find $(CSS_SRC_DIR) -name "*.less" -or -name "*.css")
+
+# generated files
+VERSION_CONFIG  = _version.yml
+DEFAULTS_CONFIG = _defaults.yml
+LANGUAGES_DATA  = $(DATA_DIR)/languages.yml
+PLUGINS_APP     = $(PLUGINS_DEST_DIR)/plugins.js
+MAIN_STYLE_FILE = $(CSS_DEST_DIR)/main.css
+
+STYLES = $(MAIN_STYLE_FILE) $(addsuffix .css,$(basename $(subst $(CSS_SRC_DIR),$(CSS_DEST_DIR),$(STYLES_SRC))))
+
+# NOTE:
+#      docs slugs are lang/version pairs, with "/" and "." replaced by "-"
+DOCS_VERSION_DIRS  = $(wildcard $(DOCS_DIR)/**/*)
+DOCS_VERSION_SLUGS = $(subst /,-,$(subst .,-,$(subst $(DOCS_DIR)/,,$(DOCS_VERSION_DIRS))))
+TOC_FILES          = $(addprefix $(TOC_DIR)/,$(addsuffix -generated.yml,$(DOCS_VERSION_SLUGS)))
+
+# variables
+# NOTE:
+#      the order of config files matters to Jekyll
+JEKYLL_CONFIGS = $(MAIN_CONFIG) $(DEFAULTS_CONFIG) $(VERSION_CONFIG)
+
+# convenience targets
+help usage default:
+	@echo ""
+	@echo "Usage:"
+	@echo ""
+	@echo "    make dev:     build site with dev config"
+	@echo "    make prod:    build site with prod config"
+	@echo "    make install: install dependencies"
+	@echo ""
+	@echo "    make data:    generate data files (Generated ToCs, $(LANGUAGES_DATA))"
+	@echo "    make configs: generate Jekyll configs ($(DEFAULTS_CONFIG), $(VERSION_CONFIG))"
+	@echo "    make styles:  generate CSS"
+	@echo "    make plugins: generate plugins app ($(PLUGINS_APP))"
+	@echo ""
+	@echo "    make clean:   remove all generated output"
+	@echo "    make nuke:    run 'make clean' and remove all dependencies"
+	@echo ""
+	@echo "Arguments:"
+	@echo ""
+	@echo "    NODOCS: (defined or undefined) - excludes docs from build"
+	@echo ""
+
+debug:
+	@echo "SCSS_SRC:" $(SCSS_SRC)
+	@echo ""
+
+data: $(TOC_FILES) $(LANGUAGES_DATA)
+configs: $(DEFAULTS_CONFIG) $(VERSION_CONFIG)
+styles: $(STYLES)
+plugins: $(PLUGINS_APP)
+
+dev: JEKYLL_CONFIGS += $(DEV_CONFIG)
+dev: JEKYLL_FLAGS += --trace
+dev: DEBUG = 1
+prod: JEKYLL_CONFIGS += $(PROD_CONFIG)
+prod: JEKYLL_FLAGS +=
+prod: DEBUG =
+dev prod: build
+
+ifdef NODOCS
+build: JEKYLL_CONFIGS += $(DOCS_EXCLUDE_CONFIG)
+endif
+
+build: JEKYLL_FLAGS += --config $(subst $(SPACE),$(COMMA),$(strip $(JEKYLL_CONFIGS)))
+build: $(JEKYLL_CONFIGS) $(STYLES) $(PLUGINS_APP)
+	$(JEKYLL) build $(JEKYLL_FLAGS)
+
+install:
+	bundle install
+	npm install
+
+# real targets
+$(PLUGINS_APP): $(PLUGINS_SRC) Makefile
+	echo "---\n---" > $@
+	$(BROWSERIFY) -t reactify -t envify $< | $(UGLIFY) >> $@
+
+$(LANGUAGES_DATA): $(BIN_DIR)/gen_languages.js Makefile
+	$(NODE) $(BIN_DIR)/gen_languages.js $(DOCS_DIR) > $@
+
+$(DEFAULTS_CONFIG): $(BIN_DIR)/gen_defaults.js Makefile
+	$(NODE) $(BIN_DIR)/gen_defaults.js $(DOCS_DIR) > $@
+
+$(VERSION_CONFIG): VERSION Makefile
+	sed -e 's/^/$(VERSION_VAR_NAME): /' < $< > $@
+
+$(TOC_FILES): $(BIN_DIR)/toc.js Makefile
+	$(NODE) $(BIN_DIR)/toc.js $(DOCS_DIR) $(DATA_DIR)
+
+$(MAIN_STYLE_FILE): $(SCSS_SRC)
+
+$(CSS_DEST_DIR)/%.css: $(CSS_SRC_DIR)/%.less Makefile
+	mkdir -p $(@D)
+	echo "---\n---" > $@
+	$(LESSC) $< >> $@
+
+$(CSS_DEST_DIR)/%.css: $(CSS_SRC_DIR)/%.scss Makefile
+	mkdir -p $(@D)
+	echo "---\n---" > $@
+	$(SASSC) $< >> $@
+
+$(CSS_DEST_DIR)/%.css: $(CSS_SRC_DIR)/%.css Makefile
+	mkdir -p $(@D)
+	echo "---\n---" > $@
+	cat $< >> $@
+
+# maintenance
+clean:
+	find . -name *.pyc -delete
+	$(RM) -r $(PROD_DIR) $(DEV_DIR)
+	$(RM) $(VERSION_CONFIG)
+	$(RM) $(DEFAULTS_CONFIG)
+	$(RM) $(TOC_FILES)
+	$(RM) $(LANGUAGES_DATA)
+	$(RM) $(PLUGINS_APP)
+	$(RM) -r $(CSS_DEST_DIR)
+
+nuke: clean
+	$(RM) -r node_modules
+	$(RM) Gemfile.lock
+
+.PHONY: clean usage help default build

http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/b0e35dad/README.md
----------------------------------------------------------------------
diff --git a/README.md b/README.md
index a15e5cf..a380888 100644
--- a/README.md
+++ b/README.md
@@ -64,13 +64,16 @@ Verify the installation by running:
 
 ## Dependencies
 
-Once Ruby and JavaScript are installed, install all dependencies by running:
+Once Ruby and JavaScript are installed, install Ruby dependencies by running:
 
     gem install bundle
     bundle install
-    npm install
 
-On some systems, administrator privileges may be required for some of the above commands.
+On some systems, the above commands need to be prefixed with `sudo`. Similarly on Windows, the `cmd` window in which those commands are to be run might need to have been "Run as Administrator."
+
+Finally, install JavaScript dependencies by running:
+
+    npm install
 
 Building
 ========
@@ -84,32 +87,24 @@ The built website will be in a folder called `build-prod`.
 Developing
 ==========
 
-To work on the website, run:
+To work on the website and see changes live as you save, run:
 
-    node_modules/.bin/gulp serve
+    node_modules/.bin/gulp watch
 
-To see changes live as you save, run:
+That command will start a server and watch the source files, regenerating the site and refreshing the browser whenever changes are made. To work on only the website without the docs, add the `--nodocs` flag, as follows:
 
-    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 `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
-
-**NOTE**: *Please don't commit any dev-specific inclusion/exclusion modifications. Keep them local to your development environment.*
+    node_modules/.bin/gulp watch --nodocs
 
 Deploying
 =========
 
 This section requires basic knowledge of SVN. If you do not know how to use SVN, refer to [this tutorial][svn].
 
-To build the full website, run:
+To build the full website (possibly excluding docs by adding `--nodocs`), run:
 
     gulp build --prod
 
-A folder called `build-prod` 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 the following command (committer access required):
+A folder called `build-prod` will be created, and will contain the built website. Then, in a directory *outside* of the `cordova-docs` repository, check out the SVN repository that contains the currently deployed website by running the following command (committer access required):
 
     cd ..
     svn checkout https://svn.apache.org/repos/asf/cordova/site cordova-website
@@ -118,7 +113,11 @@ Copy the `cordova-docs/build-prod/` directory to the `public` directory in SVN l
 
     cp -R cordova-docs/build-prod/* cordova-website/public/
 
-Finally, go into the `cordova-website` directory and commit *all* the changes introduced by the newly copied files. Some files will be new (`?` in SVN, and need to be `svn add`ed) and some files will be changed (`M` in SVN). The commit might take a while (up to 1 hour), depending on the number of files changed. To see just the `?` changes, run `svn status | grep "?"`
+Finally, go into the `cordova-website` directory and commit *all* the changes introduced by the newly copied files. Some files will be new (`?` in SVN, and need to be `svn add`ed) and some files will be changed (`M` in SVN; no action required). To see just the `?` changes, run:
+
+    svn status | grep "?"
+
+The commit might take a while (up to 1 hour), depending on the number of files changed.
 
 Working on the Documentation
 ============================
@@ -246,28 +245,38 @@ To print the list of plugin versions tested:
 Troubleshooting
 ===============
 
-* If you see `Error: EMF, too many open files`, you have to increase your `ulimit`.
-    
+## Error: EMF, too many open files
+
+Increase the maximum number of open files on the system:
+
     ulimit -n 10480
 
-* If you get errors trying to run `gem install bundle` due to permission issues, you may want to think about using a different method to install `ruby`. Checkout [rbenv][rbenvgh]. Instructions below:
+## Error: spawn ENOENT
+
+Run:
+
+    gulp clean
+
+## Permission issues during Ruby install
+
+You could try a different method to install Ruby. Checkout [rbenv][rbenvgh]. Instructions:
 
-  1. Install rbenv
+1. Install rbenv
 
-    brew install rbenv ruby-build
+        brew install rbenv ruby-build
 
-  2. Add `eval "$(rbenv init -)"` to your `.bash_profile`:
+2. Add `eval "$(rbenv init -)"` to the end of your `.bash_profile`:
 
-    echo 'eval "$(rbenv init -)"' >> ~/.bash_profile
+        echo 'eval "$(rbenv init -)"' >> ~/.bash_profile
 
-  3. Install a version of `ruby` and set it to your local version:
+3. Install a version of `ruby` and set it to your local version:
 
-    rbenv install 2.0.0-p647
-    rbenv local 2.0.0-p647
+        rbenv install 2.0.0-p647
+        rbenv local 2.0.0-p647
 
-* If you see the error `Error: spawn ENOENT`, run `gulp clean`
+## Other Problems
 
-Ask for help on the Slack channel. Join at [slack.cordova.io](http://slack.cordova.io/).
+Please ask for help on the Slack channel. Join at [slack.cordova.io](http://slack.cordova.io/).
 
 [ruby_linux]: https://www.ruby-lang.org/en/documentation/installation/#package-management-systems
 [homebrew]: http://brew.sh/

http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/b0e35dad/_dev.yml
----------------------------------------------------------------------
diff --git a/_dev.yml b/_dev.yml
index 9196edf..5c6d0b0 100644
--- a/_dev.yml
+++ b/_dev.yml
@@ -1,3 +1,5 @@
+baseurl: ""
+destination: build-dev
 exclude:
     - static/css-src
     - static/plugins

http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/b0e35dad/_nodocs.yml
----------------------------------------------------------------------
diff --git a/_nodocs.yml b/_nodocs.yml
new file mode 100644
index 0000000..60e4bc7
--- /dev/null
+++ b/_nodocs.yml
@@ -0,0 +1,4 @@
+exclude:
+    - static/css-src
+    - static/plugins
+    - docs

http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/b0e35dad/gulpfile.js
----------------------------------------------------------------------
diff --git a/gulpfile.js b/gulpfile.js
index dab5f51..48f921f 100644
--- a/gulpfile.js
+++ b/gulpfile.js
@@ -44,6 +44,7 @@ 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 NODOCS_CONFIG_FILE   = "_nodocs.yml";
 
 var VERSION_FILE      = "VERSION";
 var LANGUAGES_FILE    = path.join(DATA_DIR, "languages.yml");
@@ -51,9 +52,11 @@ 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");
 
-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(",")];
+var DEFAULT_CONFIGS = [CONFIG_FILE, DEFAULTS_CONFIG_FILE, VERSION_CONFIG_FILE];
+var DEV_CONFIGS     = [DEV_CONFIG_FILE];
+var PROD_CONFIGS    = [PROD_CONFIG_FILE];
+var DEV_FLAGS       = ["--trace"];
+var PROD_FLAGS      = [];
 
 var BASE_URL          = "";
 var YAML_FRONT_MATTER = "---\n---\n";
@@ -97,14 +100,36 @@ function getJekyllExecutable() {
     }
 }
 
+function getJekyllConfigs() {
+    var configs = DEFAULT_CONFIGS;
+
+    // add build-specific config files
+    if (gutil.env.prod) {
+        configs = configs.concat(PROD_CONFIGS);
+    } else {
+        configs = configs.concat(DEV_CONFIGS);
+    }
+
+    // add a special exclude file if "nodocs" was specified
+    if (gutil.env.nodocs) {
+        configs = configs.concat(NODOCS_CONFIG_FILE);
+    }
+
+    return configs;
+}
+
 function jekyllBuild(done) {
-    var flags  = gutil.env.prod ? PROD_FLAGS : DEV_FLAGS;
-    var jekyll = getJekyllExecutable();
+    var jekyll  = getJekyllExecutable();
+    var configs = getJekyllConfigs();
+    var flags   = gutil.env.prod ? PROD_FLAGS : DEV_FLAGS;
+
+    flags = flags.concat(["--config", configs.join(",")]);
+
     exec(jekyll, ["build"].concat(flags), done);
 }
 
 // tasks
-gulp.task("watch", ["serve"], function () {
+gulp.task("watch", [], function () {
     gulp.watch(
         [
             path.join(CSS_SRC_DIR, "**", "*"),
@@ -267,7 +292,7 @@ gulp.task("plugins", function() {
 gulp.task("configs", ["toc", "languages", "defaults", "version"]);
 gulp.task("styles", ["less", "css", "sass"]);
 gulp.task("build", ["gen-full"]);
-gulp.task("default", ["watch"]);
+gulp.task("default", ["serve"]);
 
 // convenience tasks
 gulp.task("link-bugs", function (done) {

http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/b0e35dad/package.json
----------------------------------------------------------------------
diff --git a/package.json b/package.json
index b21054c..15fcda0 100644
--- a/package.json
+++ b/package.json
@@ -38,6 +38,7 @@
     "less": "^2.5.1",
     "ncp": "^2.0.0",
     "node-dir": "^0.1.6",
+    "node-sass": "^3.4.1",
     "optimist": "^0.6.1",
     "q": "^1.4.1",
     "react": "^0.13.3",
@@ -45,6 +46,7 @@
     "reactify": "^1.1.1",
     "semver": "^5.0.3",
     "shelljs": "^0.3.0",
+    "uglifyjs": "^2.4.10",
     "vinyl-buffer": "^1.0.0",
     "vinyl-source-stream": "^1.1.0",
     "walk": "^2.3.9",


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