Repository: cordova-docs Updated Branches: refs/heads/master a65e8109a -> 4d62f605f
CB-10819 Added 'snap' command to Makefile and gulpfile. Fixed 'newversion' command. Made fetched files live under /reference/ instead of /gen/. Refactored and removed incrementversion.js in favour of simple FS commands. Added redirects for /gen/ files. Project: http://git-wip-us.apache.org/repos/asf/cordova-docs/repo Commit: http://git-wip-us.apache.org/repos/asf/cordova-docs/commit/4d62f605 Tree: http://git-wip-us.apache.org/repos/asf/cordova-docs/tree/4d62f605 Diff: http://git-wip-us.apache.org/repos/asf/cordova-docs/diff/4d62f605 Branch: refs/heads/master Commit: 4d62f605f8f17633395a6b75e85acade30ecf8e6 Parents: a65e810 Author: Dmitry Blotsky <dmitry.blot...@gmail.com> Authored: Mon Mar 7 18:21:40 2016 -0800 Committer: Dmitry Blotsky <dmitry.blot...@gmail.com> Committed: Fri Mar 18 15:42:36 2016 -0700 ---------------------------------------------------------------------- .gitignore | 2 +- Makefile | 84 +++++++--- gulpfile.js | 110 ++++++++---- package.json | 1 - tools/bin/fetch_docs.js | 167 ++++++++++++------- tools/bin/gen_defaults.js | 5 +- tools/bin/incrementversion.js | 151 ----------------- tools/bin/nextversion.js | 67 ++++++++ www/_data/fetched-files.yml | 78 +++++---- www/_data/redirects.yml | 25 ++- www/_data/toc/en-dev-manual.yml | 44 ++--- www/docs/en/dev/config_ref/images.md | 2 +- www/docs/en/dev/config_ref/index.md | 14 +- www/docs/en/dev/guide/appdev/whitelist/index.md | 2 +- www/docs/en/dev/guide/cli/index.md | 26 ++- www/docs/en/dev/guide/hybrid/plugins/index.md | 7 +- .../en/dev/guide/platforms/android/index.md | 15 +- .../dev/guide/platforms/blackberry10/index.md | 6 +- www/docs/en/dev/guide/platforms/ios/index.md | 6 +- www/docs/en/dev/guide/support/index.md | 36 ++-- 20 files changed, 484 insertions(+), 364 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/4d62f605/.gitignore ---------------------------------------------------------------------- diff --git a/.gitignore b/.gitignore index 141eced..db617e2 100644 --- a/.gitignore +++ b/.gitignore @@ -8,7 +8,7 @@ conf/fetched_docs.json www/_data/docs-versions.yml www/static/css www/static/js/plugins.js +www/docs/en/dev/reference node_modules Gemfile.lock -www/docs/en/dev/gen http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/4d62f605/Makefile ---------------------------------------------------------------------- diff --git a/Makefile b/Makefile index 260506b..0e28622 100644 --- a/Makefile +++ b/Makefile @@ -13,10 +13,18 @@ ifdef WINDOWS SHELL = cmd JEKYLL = bundle.bat exec jekyll MKDIRP = mkdir +CPR = xcopy /e +CP = copy +CAT = type +LS = ls else SHELL = sh JEKYLL = bundle exec jekyll MKDIRP = mkdir -p +CPR = cp -R +CP = cp +CAT = cat +LS = ls endif # constants @@ -36,7 +44,6 @@ PROD_DIR = build-prod CONFIG_DIR = conf DOCS_DIR = $(SRC_DIR)/docs -FETCH_DIR = $(DOCS_DIR)/en/dev/gen DATA_DIR = $(SRC_DIR)/_data TOC_DIR = $(DATA_DIR)/toc STATIC_DIR = $(SRC_DIR)/static @@ -70,6 +77,7 @@ DOCS_EXCLUDE_CONFIG = $(CONFIG_DIR)/_nodocs.yml FETCH_CONFIG = $(DATA_DIR)/fetched-files.yml PLUGINS_SRC = $(PLUGINS_SRC_DIR)/app.js VERSION_FILE = VERSION +FETCH_SCRIPT = $(BIN_DIR)/fetch_docs.js # NOTE: # the .scss files are separate because they combine into MAIN_STYLE_FILE, @@ -83,6 +91,17 @@ SCSS_SRC = $(shell find $(CSS_SRC_DIR) -name "*.scss") STYLES_SRC = $(shell find $(CSS_SRC_DIR) -name "*.less" -or -name "*.css") endif +LANGUAGES = $(shell $(LS) $(DOCS_DIR)) + +LATEST_DOCS_VERSION = $(shell $(CAT) $(VERSION_FILE)) +NEXT_DOCS_VERSION = $(shell $(NODE) $(BIN_DIR)/nextversion.js $(LATEST_DOCS_VERSION)) + +LATEST_DOCS_VERSION_SLUG = $(subst .,-,$(LATEST_DOCS_VERSION)) +NEXT_DOCS_VERSION_SLUG = $(subst .,-,$(NEXT_DOCS_VERSION)) + +DEV_DOCS = $(addprefix $(DOCS_DIR)/,$(addsuffix /dev,$(LANGUAGES))) +DEV_DOCS_TOCS = $(addprefix $(TOC_DIR)/,$(addsuffix -dev-manual.yml, $(LANGUAGES))) + # generated files VERSION_CONFIG = $(CONFIG_DIR)/_version.yml DEFAULTS_CONFIG = $(CONFIG_DIR)/_defaults.yml @@ -98,16 +117,20 @@ DOCS_VERSION_DIRS = $(filter-out %.md,$(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 +FETCH_FLAGS = --config $(FETCH_CONFIG) --docsRoot $(DOCS_DIR) +FETCHED_FILES = $(shell $(NODE) $(FETCH_SCRIPT) $(FETCH_FLAGS) --dump) + +LATEST_DOCS = $(addprefix $(DOCS_DIR)/,$(addsuffix /$(LATEST_DOCS_VERSION),$(LANGUAGES))) +LATEST_DOCS_TOCS = $(addprefix $(TOC_DIR)/,$(addsuffix -$(LATEST_DOCS_VERSION_SLUG)-manual.yml, $(LANGUAGES))) + +NEXT_DOCS = $(addprefix $(DOCS_DIR)/,$(addsuffix /$(NEXT_DOCS_VERSION),$(LANGUAGES))) +NEXT_DOCS_TOCS = $(addprefix $(TOC_DIR)/,$(addsuffix -$(NEXT_DOCS_VERSION_SLUG)-manual.yml, $(LANGUAGES))) + +# other variables # NOTE: # the order of config files matters to Jekyll JEKYLL_CONFIGS = $(MAIN_CONFIG) $(DEFAULTS_CONFIG) $(VERSION_CONFIG) - -ifdef WINDOWS -LATEST_DOCS_VERSION = $(shell type $(VERSION_FILE)) -else -LATEST_DOCS_VERSION = $(shell cat $(VERSION_FILE)) -endif +JEKYLL_FLAGS = # convenience targets help usage default: @@ -131,7 +154,7 @@ help usage default: @echo " NODOCS: (defined or undefined) - excludes docs from build" @echo "" -data: fetch $(TOC_FILES) $(DOCS_VERSION_DATA) +data: $(TOC_FILES) $(DOCS_VERSION_DATA) configs: $(DEFAULTS_CONFIG) $(VERSION_CONFIG) styles: $(STYLES) plugins: $(PLUGINS_APP) @@ -141,7 +164,6 @@ dev: JEKYLL_CONFIGS += $(DEV_CONFIG) dev: JEKYLL_FLAGS += --trace prod: JEKYLL_CONFIGS += $(PROD_CONFIG) -prod: JEKYLL_FLAGS += dev prod: build @@ -150,7 +172,7 @@ build: JEKYLL_CONFIGS += $(DOCS_EXCLUDE_CONFIG) endif build: JEKYLL_FLAGS += --config $(subst $(SPACE),$(COMMA),$(strip $(JEKYLL_CONFIGS))) -build: $(JEKYLL_CONFIGS) data styles plugins +build: $(JEKYLL_CONFIGS) fetch data styles plugins $(JEKYLL) build $(JEKYLL_FLAGS) install: @@ -160,13 +182,17 @@ install: serve: cd $(DEV_DIR) && python -m SimpleHTTPServer 8000 -$(FETCH_DIR): $(FETCH_CONFIG) $(BIN_DIR)/fetch_docs.js - $(NODE) $(BIN_DIR)/fetch_docs.js $(FETCH_CONFIG) $@ - touch $@ +fetch: $(FETCHED_FILES) + +snap: fetch $(LATEST_DOCS) $(LATEST_DOCS_TOCS) -fetch: $(FETCH_DIR) +newversion: $(NEXT_DOCS) $(NEXT_DOCS_TOCS) + echo $(NEXT_DOCS_VERSION) > $(VERSION_FILE) # real targets +$(FETCHED_FILES): $(FETCH_CONFIG) $(FETCH_SCRIPT) + $(NODE) $(FETCH_SCRIPT) $(FETCH_FLAGS) + # NOTE: # the ">>" operator appends to a file in both CMD and SH $(PLUGINS_APP): $(PLUGINS_SRC) @@ -174,21 +200,39 @@ $(PLUGINS_APP): $(PLUGINS_SRC) echo --->> $@ $(BROWSERIFY) -t reactify -t envify $< | $(UGLIFY) >> $@ -$(DOCS_VERSION_DATA): $(BIN_DIR)/gen_versions.js +$(DOCS_VERSION_DATA): $(BIN_DIR)/gen_versions.js $(DOCS_DIR) $(NODE) $(BIN_DIR)/gen_versions.js $(DOCS_DIR) > $@ -$(DEFAULTS_CONFIG): $(BIN_DIR)/gen_defaults.js $(VERSION_FILE) +$(DEFAULTS_CONFIG): $(BIN_DIR)/gen_defaults.js $(VERSION_FILE) $(DOCS_DIR) $(NODE) $(BIN_DIR)/gen_defaults.js $(DOCS_DIR) "$(LATEST_DOCS_VERSION)" > $@ $(VERSION_CONFIG): $(VERSION_FILE) sed -e "s/^/$(VERSION_VAR_NAME): /" < $< > $@ -$(TOC_FILES): $(BIN_DIR)/toc.js +$(TOC_FILES): $(BIN_DIR)/toc.js $(DOCS_DIR) $(NODE) $(BIN_DIR)/toc.js $(DOCS_DIR) $(DATA_DIR) $(MAIN_STYLE_FILE): $(SCSS_SRC) # pattern rules +$(DOCS_DIR)/%/$(LATEST_DOCS_VERSION): $(DOCS_DIR)/%/dev + $(RM) -r $@ + $(CPR) $^ $@ +ifndef WINDOWS + touch $(DOCS_DIR) +endif + +$(DOCS_DIR)/%/$(NEXT_DOCS_VERSION): $(DOCS_DIR)/%/dev + $(CPR) $^ $@ +ifndef WINDOWS + touch $(DOCS_DIR) +endif + +$(TOC_DIR)/%-$(LATEST_DOCS_VERSION_SLUG)-manual.yml: $(TOC_DIR)/%-dev-manual.yml + $(CP) $^ $@ + +$(TOC_DIR)/%-$(NEXT_DOCS_VERSION_SLUG)-manual.yml: $(TOC_DIR)/%-dev-manual.yml + $(CP) $^ $@ # NODE: # $(@D) means "directory part of target" @@ -226,16 +270,16 @@ endif clean: $(RM) -r $(PROD_DIR) $(DEV_DIR) - $(RM) -r $(FETCH_DIR) $(RM) $(VERSION_CONFIG) $(RM) $(DEFAULTS_CONFIG) $(RM) $(TOC_FILES) $(RM) $(DOCS_VERSION_DATA) $(RM) $(PLUGINS_APP) $(RM) -r $(CSS_DEST_DIR) + $(RM) $(FETCHED_FILES) nuke: clean $(RM) -r node_modules $(RM) Gemfile.lock -.PHONY: clean usage help default build +.PHONY: clean usage help default build $(DEV_DOCS) http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/4d62f605/gulpfile.js ---------------------------------------------------------------------- diff --git a/gulpfile.js b/gulpfile.js index aa305a9..0afd09d 100644 --- a/gulpfile.js +++ b/gulpfile.js @@ -24,6 +24,10 @@ var uglify = require("gulp-uglify"); var envify = require("envify"); var htmllint = require("gulp-htmllint"); var crawler = require("simplecrawler"); +var ncp = require("ncp"); + +var nextversion = require("./tools/bin/nextversion"); +var util = require("./tools/bin/util"); // constants var ROOT_DIR = "."; @@ -35,7 +39,7 @@ var PROD_DIR = path.join(ROOT_DIR, "build-prod"); 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 FETCH_DIR = path.join(DOCS_DIR, "en", "dev", "gen"); +var FETCH_DIR = path.join(DOCS_DIR, "en", "dev", "reference"); 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"); @@ -62,18 +66,20 @@ var PROD_CONFIGS = [PROD_CONFIG_FILE]; var DEV_FLAGS = ["--trace"]; var PROD_FLAGS = []; -var BASE_URL = ""; -var YAML_FRONT_MATTER = "---\n---\n"; -var WATCH_INTERVAL = 1000; // in milliseconds -var VERSION_VAR_NAME = "latest_docs_version"; +var BASE_URL = ""; +var YAML_FRONT_MATTER = "---\n---\n"; +var WATCH_INTERVAL = 1000; // in milliseconds +var VERSION_VAR_NAME = "latest_docs_version"; +var LATEST_DOCS_VERSION = fs.readFileSync(VERSION_FILE, 'utf-8').trim(); +var NEXT_DOCS_VERSION = nextversion.getNextVersion(LATEST_DOCS_VERSION); +var LANGUAGES = util.listdirsSync(DOCS_DIR); var PROD_BY_DEFAULT = false; // 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; -gutil.env.latestDocsVersion = fs.readFileSync(VERSION_FILE, 'utf-8'); +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) { @@ -133,6 +139,50 @@ function jekyllBuild(done) { exec(bundle, ["exec", "jekyll", "build"].concat(flags), done); } +function copyDocsVersion(oldVersion, newVersion, cb) { + + // copying a folder and a ToC file for each language + var numCopyOperations = LANGUAGES.length * 2; + + // pseudo-CV (condition variable) + var numCopied = 0; + function doneCopying(error) { + + if (error) { + cb(error); + return; + } + + // call callback if all folders have finished copying + numCopied += 1; + if (numCopied === numCopyOperations) { + cb(); + } + } + + // create a new version for each language + LANGUAGES.forEach(function (languageName) { + + // get files to copy + var oldVersionDocs = path.join(DOCS_DIR, languageName, oldVersion); + var oldVersionToc = path.join(TOC_DIR, util.manualTocfileName(languageName, oldVersion)); + var newVersionDocs = path.join(DOCS_DIR, languageName, newVersion); + var newVersionToc = path.join(TOC_DIR, util.manualTocfileName(languageName, newVersion)); + + var copyOptions = { + stopOnErr: true + }; + + // copy docs + console.log(oldVersionDocs + " -> " + newVersionDocs); + ncp.ncp(oldVersionDocs, newVersionDocs, copyOptions, doneCopying); + + // copy ToC + console.log(oldVersionToc + " -> " + newVersionToc); + ncp.ncp(oldVersionToc, newVersionToc, copyOptions, doneCopying); + }); +} + // tasks gulp.task("default", ["help"]); @@ -164,11 +214,8 @@ gulp.task("help", function () { gutil.log(""); gutil.log(" watch serve + then watch all source files and regenerate as necessary"); gutil.log(""); - gutil.log(" link-bugs replace CB-XXXX references with nice "); - gutil.log(""); - gutil.log(" newversion create a new docs version from current dev version"); - gutil.log(" --version the new version number (must be greater than the current latest version)"); - gutil.log(" --language only increment the version for the given language"); + gutil.log(" link-bugs replace CB-XXXX references with nice links"); + gutil.log(" newversion create the next docs version from current dev version"); gutil.log(""); gutil.log(" help show this text"); gutil.log(" clean remove all generated files and folders"); @@ -251,7 +298,7 @@ gulp.task("regen", ["jekyll"], function () { gulp.task("fetch", function (done) { if (!fs.existsSync(FETCH_DIR)) { - exec("node", [bin("fetch_docs.js"), FETCH_CONFIG, FETCH_DIR], done); + exec("node", [bin("fetch_docs.js"), "--config", FETCH_CONFIG, '--docsRoot', DOCS_DIR], done); } else { gutil.log(gutil.colors.yellow( "Skipping fetching external docs. Run 'gulp clean' first to initiate another fetch.")); @@ -282,7 +329,7 @@ gulp.task("version", function () { }); gulp.task("defaults", function () { - return execPiped("node", [bin("gen_defaults.js"), DOCS_DIR, gutil.env.latestDocsVersion], DEFAULTS_CONFIG_FILE) + return execPiped("node", [bin("gen_defaults.js"), DOCS_DIR, LATEST_DOCS_VERSION], DEFAULTS_CONFIG_FILE) .pipe(gulp.dest(ROOT_DIR)); }); @@ -370,21 +417,28 @@ gulp.task("lint", function() { 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; - } + copyDocsVersion("dev", NEXT_DOCS_VERSION, function (error) { - var args = [bin("incrementversion.js"), DOCS_DIR, TOC_DIR, gutil.env.version]; + if (error) { + console.error(error); + done(); + return; + } - if (gutil.env.language) { - args.push(gutil.env.language); - } + // finally update the version file with the new version + fs.writeFile(VERSION_FILE, NEXT_DOCS_VERSION + "\n", done); + }); +}); + +gulp.task("snap", function(done) { + + // remove current version first + LANGUAGES.forEach(function (languageName) { + var languageLatestDocs = path.join(DOCS_DIR, languageName, LATEST_DOCS_VERSION); + remove(languageLatestDocs); + }); - exec("node", args, done); + copyDocsVersion("dev", LATEST_DOCS_VERSION, done); }); gulp.task("checklinks", function(done) { http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/4d62f605/package.json ---------------------------------------------------------------------- diff --git a/package.json b/package.json index 15fcda0..52ce720 100644 --- a/package.json +++ b/package.json @@ -44,7 +44,6 @@ "react": "^0.13.3", "react-tools": "^0.13.3", "reactify": "^1.1.1", - "semver": "^5.0.3", "shelljs": "^0.3.0", "uglifyjs": "^2.4.10", "vinyl-buffer": "^1.0.0", http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/4d62f605/tools/bin/fetch_docs.js ---------------------------------------------------------------------- diff --git a/tools/bin/fetch_docs.js b/tools/bin/fetch_docs.js index 3c27f0c..b64e73e 100644 --- a/tools/bin/fetch_docs.js +++ b/tools/bin/fetch_docs.js @@ -23,28 +23,19 @@ var https = require("https"); var path = require("path"); var child_process = require("child_process"); var yaml = require("js-yaml"); +var optimist = require("optimist"); var util = require("./util"); // constants -var DEFAULT_REPO_PATH = "README.md"; +var DEFAULT_REPO_PATH = "README.md"; +var DEFAULT_VERSION_NAME = "dev"; +var DEFAULT_LANGUAGE_NAME = "en"; -function generateFrontMatter(fetchedFile) { - - var frontMatter = { - edit_link: fetchedFile.editLink, - permalink: fetchedFile.permalink, - }; - - // set special values for plugins - if (isPluginName(fetchedFile.packageName)) { - frontMatter.plugin_name = fetchedFile.packageName; - frontMatter.plugin_version = fetchedFile.version; - } - - return frontMatter; -} +var THIS_FILE = path.basename(__filename); +var WARNING_COMMENT = "<!-- WARNING: This file is generated. See " + THIS_FILE + ". -->\n\n"; +// helpers function isPluginName(packageName) { return packageName.match(/cordova-plugin-.*/); } @@ -96,8 +87,8 @@ function getFetchedFileConfig(entry) { return; } - if (!destConfig.permalink) { - console.error("entry '" + entry.toString() + "' missing 'permalink' in 'dest'"); + if (!destConfig.path) { + console.error("entry '" + entry.toString() + "' missing 'path' in 'dest'"); return; } @@ -114,13 +105,23 @@ function getFetchedFileConfig(entry) { srcConfig.commit = getLatestRelease(srcConfig.packageName); } + // make front matter + var frontMatter = { + edit_link: getRepoEditURI(srcConfig.repoName, srcConfig.commit, srcConfig.path), + title: srcConfig.packageName + } + + // set special front matter values for plugins + if (isPluginName(srcConfig.packageName)) { + frontMatter.plugin_name = srcConfig.packageName; + frontMatter.plugin_version = srcConfig.commit; + } + // set returned values var fetchedFileConfig = { - packageName: srcConfig.packageName, - version: srcConfig.commit, - editLink: getRepoEditURI(srcConfig.repoName, srcConfig.commit, srcConfig.path), - permalink: destConfig.permalink, + frontMatter: frontMatter, downloadURI: getRepoFileURI(srcConfig.repoName, srcConfig.commit, srcConfig.path), + savePath: destConfig.path }; return fetchedFileConfig; @@ -139,39 +140,35 @@ function setFrontMatter(text, frontMatter) { return util.setFrontMatterString(text, frontMatterString); } -// main -function main () { - - var configFile = process.argv[2]; - var fetchRoot = process.argv[3]; - - // validate args - if (!configFile) { - console.error("Please specify config file."); - process.exit(1); - } +function dumpEntries(downloadPrefix, entries) { + entries.forEach(function (entry) { - if (!fetchRoot) { - console.error("Please specify fetch root."); - process.exit(1); - } + // validate entry's dest config + if (!entry.dest) { + console.error("entry '" + entry.toString() + "' missing 'dest'"); + return; + } - if (!fs.existsSync(configFile)) { - console.error("Config file doesn't exist."); - process.exit(); - } + if (!entry.dest.path) { + console.error("entry '" + entry.toString() + "' missing 'path' in 'dest'"); + return; + } - // ensure that the root for all fetched files exists - if (!fs.existsSync(fetchRoot)) { - fse.mkdirsSync(fetchRoot); - } + // print the save path for the entry + if (entry.dest && entry.dest.path) { + var filePath = path.join(downloadPrefix, entry.dest.path); + console.log(filePath); - // get config - var fetchConfig = fs.readFileSync(configFile); - var configEntries = yaml.load(fetchConfig); + // error out on invalid entries + } else { + console.error("Invalid dest: " + entry); + process.exit(1); + } + }); +} - // fetch all files - configEntries.forEach(function (entry) { +function downloadEntries(downloadPrefix, entries) { + entries.forEach(function (entry) { // verify and process entry var fetchedFileConfig = getFetchedFileConfig(entry); @@ -181,8 +178,13 @@ function main () { // get info for fetching var fetchURI = fetchedFileConfig.downloadURI; - var outFileName = fetchedFileConfig.packageName + ".md"; - var outFilePath = path.join(fetchRoot, outFileName); + var outFilePath = path.join(downloadPrefix, fetchedFileConfig.savePath); + var outFileDir = path.dirname(outFilePath); + + // create directory for the file if it doesn't exist + if (!fs.existsSync(outFileDir)) { + fse.mkdirsSync(outFileDir); + } console.log(fetchURI + " -> " + outFilePath); @@ -209,12 +211,15 @@ function main () { // merge new front matter and file's // own front matter (if it had any) - var newFrontMatter = generateFrontMatter(fetchedFileConfig); + var newFrontMatter = fetchedFileConfig.frontMatter; var fileFrontMatter = getFrontMatter(fileContents); var mergedFrontMatter = util.mergeObjects(newFrontMatter, fileFrontMatter); - // set merged file matter in the file - var augmentedContents = setFrontMatter(fileContents, mergedFrontMatter); + // add a warning and set the merged file matter in the file + var contentsOnly = util.stripFrontMatter(fileContents); + contentsOnly = WARNING_COMMENT + contentsOnly; + + var augmentedContents = setFrontMatter(contentsOnly, mergedFrontMatter); // write out the file outFile.end(augmentedContents); @@ -222,8 +227,58 @@ function main () { }).on('error', function(e) { console.error(e); }); - }); + }); // http request }); // entries } +// main +function main () { + + // get args + var argv = optimist + .usage("Usage: $0 [options]") + .demand("config") + .demand("docsRoot") + .string("version") + .string("language") + .boolean("dump") + .describe("config", ".yml file listing fetched files") + .describe("docsRoot", "docs root directory") + .describe("version", "version in which to save the downloaded files").default("version", DEFAULT_VERSION_NAME) + .describe("language", "language in which to save the downloaded files").default("language", DEFAULT_LANGUAGE_NAME) + .describe("dump", "only print the downloaded files") + .argv; + + var configFile = argv.config; + var docsRoot = argv.docsRoot; + var targetVersion = argv.version; + var targetLanguage = argv.language; + var printOnly = argv.dump; + var downloadPrefix = path.join(docsRoot, targetLanguage, targetVersion); + + // validate args + if (!fs.existsSync(configFile)) { + console.error("Config file doesn't exist."); + process.exit(); + } + + if (!fs.existsSync(docsRoot)) { + console.error("Docs root doesn't exist."); + process.exit(); + } + + // get config + var fetchConfig = fs.readFileSync(configFile); + var configEntries = yaml.load(fetchConfig); + + // just dump entries if --dump was passed + if (printOnly === true) { + dumpEntries(downloadPrefix, configEntries); + + // otherwise, fetch them + } else { + downloadEntries(downloadPrefix, configEntries); + } +} + main(); http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/4d62f605/tools/bin/gen_defaults.js ---------------------------------------------------------------------- diff --git a/tools/bin/gen_defaults.js b/tools/bin/gen_defaults.js index 61dcbc5..e0c7a9f 100644 --- a/tools/bin/gen_defaults.js +++ b/tools/bin/gen_defaults.js @@ -45,8 +45,6 @@ function main () { var rootDir = process.argv[2]; var latestVersionName = process.argv[3]; - var config = {"defaults": []}; - if (!rootDir) { console.error(USAGE); console.error("Please specify the docs root directory from which to generate defaults."); @@ -59,6 +57,9 @@ function main () { process.exit(1); } + // create defaults config + var config = {"defaults": []}; + // set defaults for each language util.listdirsSync(rootDir).forEach(function (langName) { http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/4d62f605/tools/bin/incrementversion.js ---------------------------------------------------------------------- diff --git a/tools/bin/incrementversion.js b/tools/bin/incrementversion.js deleted file mode 100755 index bcd5e39..0000000 --- a/tools/bin/incrementversion.js +++ /dev/null @@ -1,151 +0,0 @@ -// 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 = "dev"; -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 by transforming the dev ToC file - if (fs.existsSync(devTocfilePath)) { - - // compute replacement strings - var devVersionString = "/" + DEV_VERSION_NAME + "/"; - var newVersionString = "/" + newVersion + "/"; - - // replace dev version name with new version name - var devToc = fs.readFileSync(devTocfilePath, ENCODING); - var newToc = devToc.replace(new RegExp(devVersionString, "g"), newVersionString) - 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/4d62f605/tools/bin/nextversion.js ---------------------------------------------------------------------- diff --git a/tools/bin/nextversion.js b/tools/bin/nextversion.js new file mode 100755 index 0000000..7050571 --- /dev/null +++ b/tools/bin/nextversion.js @@ -0,0 +1,67 @@ +// 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"; + +function getNextVersion(previousVersion) { + + // get previous version number + // NOTE: + // only versions of the form N.x are accepted + var previousVersionMatch = previousVersion.match(/^(\d+)\.x$/); + if (!previousVersionMatch) { + throw "invalid version"; + } + + // get next major version + var previousMajor = previousVersionMatch[1]; + var nextMajor = parseInt(previousMajor) + 1; + + // create next version + var nextVersion = nextMajor + ".x"; + + return nextVersion; +} + +function main() { + + // get arg + var previousVersion = process.argv[2]; + if (!previousVersion) { + console.error("no version specified"); + process.exit(1); + } + + // try to get the next version + var nextVersion = null; + try { + nextVersion = getNextVersion(previousVersion); + } catch (e) { + console.error(e); + process.exit(1); + } + + console.log(nextVersion); +} + +module.exports = { + getNextVersion: getNextVersion +}; + +if (require.main === module) { + main(); +} http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/4d62f605/www/_data/fetched-files.yml ---------------------------------------------------------------------- diff --git a/www/_data/fetched-files.yml b/www/_data/fetched-files.yml index d124bc0..afd9357 100644 --- a/www/_data/fetched-files.yml +++ b/www/_data/fetched-files.yml @@ -1,12 +1,12 @@ # REFERENCE ENTRY: # - -# src: # required -# repoName: "apache/cordova-cli" # required -# packageName: "cordova" # if empty: second part of repoName -# commit: "master" # if empty: latest in NPM -# path: "relative/path/to/file/in/repo.md" # if empty: "README.md" -# dest: # required -# permalink: "/absolute/path/on/cordova/site/index.html" # required +# src: # required +# repoName: "apache/cordova-cli" # required +# packageName: "cordova" # if empty: second part of repoName +# commit: "master" # if empty: latest in NPM +# path: "relative/path/to/file/in/repo.md" # if empty: "README.md" +# dest: # required +# path: "relative/path/in/docs/version.md" # required - src: repoName: "apache/cordova-cli" @@ -14,131 +14,151 @@ commit: "master" path: "doc/readme.md" dest: - permalink: "/docs/en/dev/cordova-cli/index.html" + path: "reference/cordova-cli/index.md" - src: repoName: "apache/cordova-plugin-battery-status" packageName: "cordova-plugin-battery-status" + commit: "master" dest: - permalink: "/docs/en/dev/cordova-plugin-battery-status/index.html" + path: "reference/cordova-plugin-battery-status/index.md" - src: repoName: "apache/cordova-plugin-camera" packageName: "cordova-plugin-camera" commit: "master" dest: - permalink: "/docs/en/dev/cordova-plugin-camera/index.html" + path: "reference/cordova-plugin-camera/index.md" - src: repoName: "apache/cordova-plugin-console" packageName: "cordova-plugin-console" + commit: "master" dest: - permalink: "/docs/en/dev/cordova-plugin-console/index.html" + path: "reference/cordova-plugin-console/index.md" - src: repoName: "apache/cordova-plugin-contacts" packageName: "cordova-plugin-contacts" + commit: "master" dest: - permalink: "/docs/en/dev/cordova-plugin-contacts/index.html" + path: "reference/cordova-plugin-contacts/index.md" - src: repoName: "apache/cordova-plugin-device" packageName: "cordova-plugin-device" + commit: "master" dest: - permalink: "/docs/en/dev/cordova-plugin-device/index.html" + path: "reference/cordova-plugin-device/index.md" - src: repoName: "apache/cordova-plugin-device-motion" packageName: "cordova-plugin-device-motion" + commit: "master" dest: - permalink: "/docs/en/dev/cordova-plugin-device-motion/index.html" + path: "reference/cordova-plugin-device-motion/index.md" - src: repoName: "apache/cordova-plugin-device-orientation" packageName: "cordova-plugin-device-orientation" + commit: "master" dest: - permalink: "/docs/en/dev/cordova-plugin-device-orientation/index.html" + path: "reference/cordova-plugin-device-orientation/index.md" - src: repoName: "apache/cordova-plugin-dialogs" packageName: "cordova-plugin-dialogs" + commit: "master" dest: - permalink: "/docs/en/dev/cordova-plugin-dialogs/index.html" + path: "reference/cordova-plugin-dialogs/index.md" - src: repoName: "apache/cordova-plugin-file" packageName: "cordova-plugin-file" + commit: "master" dest: - permalink: "/docs/en/dev/cordova-plugin-file/index.html" + path: "reference/cordova-plugin-file/index.md" - src: repoName: "apache/cordova-plugin-file-transfer" packageName: "cordova-plugin-file-transfer" + commit: "master" dest: - permalink: "/docs/en/dev/cordova-plugin-file-transfer/index.html" + path: "reference/cordova-plugin-file-transfer/index.md" - src: repoName: "apache/cordova-plugin-geolocation" packageName: "cordova-plugin-geolocation" + commit: "master" dest: - permalink: "/docs/en/dev/cordova-plugin-geolocation/index.html" + path: "reference/cordova-plugin-geolocation/index.md" - src: repoName: "apache/cordova-plugin-globalization" packageName: "cordova-plugin-globalization" + commit: "master" dest: - permalink: "/docs/en/dev/cordova-plugin-globalization/index.html" + path: "reference/cordova-plugin-globalization/index.md" - src: repoName: "apache/cordova-plugin-inappbrowser" packageName: "cordova-plugin-inappbrowser" + commit: "master" dest: - permalink: "/docs/en/dev/cordova-plugin-inappbrowser/index.html" + path: "reference/cordova-plugin-inappbrowser/index.md" - src: repoName: "apache/cordova-plugin-media" packageName: "cordova-plugin-media" + commit: "master" dest: - permalink: "/docs/en/dev/cordova-plugin-media/index.html" + path: "reference/cordova-plugin-media/index.md" - src: repoName: "apache/cordova-plugin-media-capture" packageName: "cordova-plugin-media-capture" + commit: "master" dest: - permalink: "/docs/en/dev/cordova-plugin-media-capture/index.html" + path: "reference/cordova-plugin-media-capture/index.md" - src: repoName: "apache/cordova-plugin-network-information" packageName: "cordova-plugin-network-information" + commit: "master" dest: - permalink: "/docs/en/dev/cordova-plugin-network-information/index.html" + path: "reference/cordova-plugin-network-information/index.md" - src: repoName: "apache/cordova-plugin-splashscreen" packageName: "cordova-plugin-splashscreen" + commit: "master" dest: - permalink: "/docs/en/dev/cordova-plugin-splashscreen/index.html" + path: "reference/cordova-plugin-splashscreen/index.md" - src: repoName: "apache/cordova-plugin-vibration" packageName: "cordova-plugin-vibration" + commit: "master" dest: - permalink: "/docs/en/dev/cordova-plugin-vibration/index.html" + path: "reference/cordova-plugin-vibration/index.md" - src: repoName: "apache/cordova-plugin-statusbar" packageName: "cordova-plugin-statusbar" + commit: "master" dest: - permalink: "/docs/en/dev/cordova-plugin-statusbar/index.html" + path: "reference/cordova-plugin-statusbar/index.md" - src: repoName: "apache/cordova-plugin-whitelist" packageName: "cordova-plugin-whitelist" + commit: "master" dest: - permalink: "/docs/en/dev/cordova-plugin-whitelist/index.html" + path: "reference/cordova-plugin-whitelist/index.md" - src: repoName: "apache/cordova-plugin-legacy-whitelist" packageName: "cordova-plugin-legacy-whitelist" + commit: "master" dest: - permalink: "/docs/en/dev/cordova-plugin-legacy-whitelist/index.html" + path: "reference/cordova-plugin-legacy-whitelist/index.md" http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/4d62f605/www/_data/redirects.yml ---------------------------------------------------------------------- diff --git a/www/_data/redirects.yml b/www/_data/redirects.yml index 15388ab..aff8e69 100644 --- a/www/_data/redirects.yml +++ b/www/_data/redirects.yml @@ -3,7 +3,7 @@ # redirects paths relative to / general: - - {old: "plugins/authors.html", new: "docs/en/latest/guide/hybrid/plugins/index.html#publishing-plugins" } + - {old: "plugins/authors.html", new: "docs/en/latest/guide/hybrid/plugins/index.html#publishing-plugins"} # redirects paths relative to /docs/XX/ docs: @@ -24,6 +24,29 @@ docs: - {old: "latest/guide/platforms/win8/win10-support.html", new: "latest/guide/platforms/win8/index.html"} - {old: "latest/cordova/plugins/pluginapis.html", new: "deprecated.html"} + - {old: "latest/cordova-cli/index.html", new: "latest/reference/cordova-cli/index.html"} + - {old: "latest/cordova-plugin-battery-status/index.html", new: "latest/reference/cordova-plugin-battery-status/index.html"} + - {old: "latest/cordova-plugin-camera/index.html", new: "latest/reference/cordova-plugin-camera/index.html"} + - {old: "latest/cordova-plugin-console/index.html", new: "latest/reference/cordova-plugin-console/index.html"} + - {old: "latest/cordova-plugin-contacts/index.html", new: "latest/reference/cordova-plugin-contacts/index.html"} + - {old: "latest/cordova-plugin-device/index.html", new: "latest/reference/cordova-plugin-device/index.html"} + - {old: "latest/cordova-plugin-device-motion/index.html", new: "latest/reference/cordova-plugin-device-motion/index.html"} + - {old: "latest/cordova-plugin-device-orientation/index.html", new: "latest/reference/cordova-plugin-device-orientation/index.html"} + - {old: "latest/cordova-plugin-dialogs/index.html", new: "latest/reference/cordova-plugin-dialogs/index.html"} + - {old: "latest/cordova-plugin-file/index.html", new: "latest/reference/cordova-plugin-file/index.html"} + - {old: "latest/cordova-plugin-file-transfer/index.html", new: "latest/reference/cordova-plugin-file-transfer/index.html"} + - {old: "latest/cordova-plugin-geolocation/index.html", new: "latest/reference/cordova-plugin-geolocation/index.html"} + - {old: "latest/cordova-plugin-globalization/index.html", new: "latest/reference/cordova-plugin-globalization/index.html"} + - {old: "latest/cordova-plugin-inappbrowser/index.html", new: "latest/reference/cordova-plugin-inappbrowser/index.html"} + - {old: "latest/cordova-plugin-media/index.html", new: "latest/reference/cordova-plugin-media/index.html"} + - {old: "latest/cordova-plugin-media-capture/index.html", new: "latest/reference/cordova-plugin-media-capture/index.html"} + - {old: "latest/cordova-plugin-network-information/index.html", new: "latest/reference/cordova-plugin-network-information/index.html"} + - {old: "latest/cordova-plugin-splashscreen/index.html", new: "latest/reference/cordova-plugin-splashscreen/index.html"} + - {old: "latest/cordova-plugin-vibration/index.html", new: "latest/reference/cordova-plugin-vibration/index.html"} + - {old: "latest/cordova-plugin-statusbar/index.html", new: "latest/reference/cordova-plugin-statusbar/index.html"} + - {old: "latest/cordova-plugin-whitelist/index.html", new: "latest/reference/cordova-plugin-whitelist/index.html"} + - {old: "latest/cordova-plugin-legacy-whitelist/index.html", new: "latest/reference/cordova-plugin-legacy-whitelist/index.html"} + # redirects paths relative to /docs/XX/YYY/ docs-global: - {old: "config_ref_images.md.html", new: "config_ref/images.html"} http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/4d62f605/www/_data/toc/en-dev-manual.yml ---------------------------------------------------------------------- diff --git a/www/_data/toc/en-dev-manual.yml b/www/_data/toc/en-dev-manual.yml index 8574e97..5d437bc 100644 --- a/www/_data/toc/en-dev-manual.yml +++ b/www/_data/toc/en-dev-manual.yml @@ -83,7 +83,7 @@ - name: "Events" url: "cordova/events/events.html" - name: "CLI" - url: "cordova-cli/index.html" + url: "reference/cordova-cli/index.html" - name: "Hooks" url: "guide/appdev/hooks/index.html" - name: "Plugin.xml" @@ -91,47 +91,47 @@ - name: "Plugin APIs" children: - name: Battery Status - url: "cordova-plugin-battery-status/index.html" + url: "reference/cordova-plugin-battery-status/index.html" - name: Camera - url: "cordova-plugin-camera/index.html" + url: "reference/cordova-plugin-camera/index.html" - name: Console - url: "cordova-plugin-console/index.html" + url: "reference/cordova-plugin-console/index.html" - name: Contacts - url: "cordova-plugin-contacts/index.html" + url: "reference/cordova-plugin-contacts/index.html" - name: Device - url: "cordova-plugin-device/index.html" + url: "reference/cordova-plugin-device/index.html" - name: Device Motion - url: "cordova-plugin-device-motion/index.html" + url: "reference/cordova-plugin-device-motion/index.html" - name: Device Orientation - url: "cordova-plugin-device-orientation/index.html" + url: "reference/cordova-plugin-device-orientation/index.html" - name: Dialogs - url: "cordova-plugin-dialogs/index.html" + url: "reference/cordova-plugin-dialogs/index.html" - name: File - url: "cordova-plugin-file/index.html" + url: "reference/cordova-plugin-file/index.html" - name: File Transfer - url: "cordova-plugin-file-transfer/index.html" + url: "reference/cordova-plugin-file-transfer/index.html" - name: Geolocation - url: "cordova-plugin-geolocation/index.html" + url: "reference/cordova-plugin-geolocation/index.html" - name: Globalization - url: "cordova-plugin-globalization/index.html" + url: "reference/cordova-plugin-globalization/index.html" - name: Inappbrowser - url: "cordova-plugin-inappbrowser/index.html" + url: "reference/cordova-plugin-inappbrowser/index.html" - name: Media - url: "cordova-plugin-media/index.html" + url: "reference/cordova-plugin-media/index.html" - name: Media Capture - url: "cordova-plugin-media-capture/index.html" + url: "reference/cordova-plugin-media-capture/index.html" - name: Network Information - url: "cordova-plugin-network-information/index.html" + url: "reference/cordova-plugin-network-information/index.html" - name: Splashscreen - url: "cordova-plugin-splashscreen/index.html" + url: "reference/cordova-plugin-splashscreen/index.html" - name: Vibration - url: "cordova-plugin-vibration/index.html" + url: "reference/cordova-plugin-vibration/index.html" - name: Statusbar - url: "cordova-plugin-statusbar/index.html" + url: "reference/cordova-plugin-statusbar/index.html" - name: Whitelist - url: "cordova-plugin-whitelist/index.html" + url: "reference/cordova-plugin-whitelist/index.html" - name: Legacy Whitelist - url: "cordova-plugin-legacy-whitelist/index.html" + url: "reference/cordova-plugin-legacy-whitelist/index.html" # - name: "Tutorials" # children: # - name: "Share your app in source control" http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/4d62f605/www/docs/en/dev/config_ref/images.md ---------------------------------------------------------------------- diff --git a/www/docs/en/dev/config_ref/images.md b/www/docs/en/dev/config_ref/images.md index 313686a..c6f302c 100644 --- a/www/docs/en/dev/config_ref/images.md +++ b/www/docs/en/dev/config_ref/images.md @@ -190,4 +190,4 @@ Though it is not recommended but is still possible to define icons using `width` ``` [blackberry_icon]: http://developer.blackberry.com/html5/documentation/icon_element.html -[splashscreen_plugin]: ../cordova-plugin-splashscreen/ +[splashscreen_plugin]: ../reference/cordova-plugin-splashscreen/ http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/4d62f605/www/docs/en/dev/config_ref/index.md ---------------------------------------------------------------------- diff --git a/www/docs/en/dev/config_ref/index.md b/www/docs/en/dev/config_ref/index.md index e5dee88..f15491e 100644 --- a/www/docs/en/dev/config_ref/index.md +++ b/www/docs/en/dev/config_ref/index.md @@ -174,7 +174,7 @@ platform. See [Customize icons topic](images.html) for more information. Attributes(type) | Description ----------------- | ------------ href(string) | *Required* <br/> Defines the set of external domains the WebView is allowed to navigate to. - See the cordova-plugin-whitelist [cordova-plugin-whitelist](../cordova-plugin-whitelist/index.html#navigation-whitelist) for details. + See the cordova-plugin-whitelist [cordova-plugin-whitelist][whitelist_navigation] for details. Examples: @@ -192,7 +192,7 @@ platform. See [Customize icons topic](images.html) for more information. Attributes(type) | Description ----------------- | ------------ href(string) | *Required* <br/> Defines which URLs the app is allowed to ask the system to open. - See the cordova-plugin-whitelist [cordova-plugin-whitelist](../cordova-plugin-whitelist/index.html#intent-whitelist) for details. + See the cordova-plugin-whitelist [cordova-plugin-whitelist][whitelist_intent] for details. Examples: @@ -209,7 +209,7 @@ platform. See [Customize icons topic](images.html) for more information. Attributes(type) | Description ----------------- | ------------ name(string) | *Required* <br/> Name of the platform to be restored - spec(string) | *Required* <br/> Details about the platform to be restored. This could be a ```major.minor.patch``` version number, a directory containing the platform or a url pointing to a git repository. This information will be used to retrieve the platform code to restore from NPM, a local directory or a git repository. See [Platform Spec](../cordova-cli/index.html#platform-spec) for further details. + spec(string) | *Required* <br/> Details about the platform to be restored. This could be a ```major.minor.patch``` version number, a directory containing the platform or a url pointing to a git repository. This information will be used to retrieve the platform code to restore from NPM, a local directory or a git repository. See [Platform Spec][platform_spec] for further details. Examples: @@ -224,7 +224,7 @@ platform. See [Customize icons topic](images.html) for more information. Attributes(type) | Description ----------------- | ------------ name(string) | *Required* <br/> Name of the plugin to be restored - spec(string) | *Required* <br/> Details about the plugin to be restored. This could be a ```major.minor.patch``` version number, a directory containing the plugin or a url pointing to a git repository. This information will be used to retrieve the plugin code to restore from NPM, a local directory or a git repository. See [Plugin Spec](../cordova-cli/index.html#plugin-spec) for further details. + spec(string) | *Required* <br/> Details about the plugin to be restored. This could be a ```major.minor.patch``` version number, a directory containing the plugin or a url pointing to a git repository. This information will be used to retrieve the plugin code to restore from NPM, a local directory or a git repository. See [Plugin Spec][plugin_spec] for further details. Examples: @@ -466,4 +466,8 @@ platform. See [Customize icons topic](images.html) for more information. </widget> ``` -[uses-sdk]: http://developer.android.com/guide/topics/manifest/uses-sdk-element.html +[uses-sdk]: http://developer.android.com/guide/topics/manifest/uses-sdk-element.html +[platform_spec]: ../reference/cordova-cli/index.html#platform-spec +[plugin_spec]: ../reference/cordova-cli/index.html#plugin-spec +[whitelist_navigation]: ../reference/cordova-plugin-whitelist/index.html#navigation-whitelist +[whitelist_intent]: ../reference/cordova-plugin-whitelist/index.html#intent-whitelist http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/4d62f605/www/docs/en/dev/guide/appdev/whitelist/index.md ---------------------------------------------------------------------- diff --git a/www/docs/en/dev/guide/appdev/whitelist/index.md b/www/docs/en/dev/guide/appdev/whitelist/index.md index 601645e..674cd16 100644 --- a/www/docs/en/dev/guide/appdev/whitelist/index.md +++ b/www/docs/en/dev/guide/appdev/whitelist/index.md @@ -150,7 +150,7 @@ For more information on support, see BlackBerry's documentation on the The whitelisting rules for Windows Phone 8 are found in the app's `config.xml` file. -[wlp]: ../../../cordova-plugin-whitelist/ +[wlp]: ../../../reference/cordova-plugin-whitelist/ [1]: http://www.w3.org/TR/widgets-access/ [2]: http://google.com [3]: https://google.com http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/4d62f605/www/docs/en/dev/guide/cli/index.md ---------------------------------------------------------------------- diff --git a/www/docs/en/dev/guide/cli/index.md b/www/docs/en/dev/guide/cli/index.md index f75bb7f..022a497 100644 --- a/www/docs/en/dev/guide/cli/index.md +++ b/www/docs/en/dev/guide/cli/index.md @@ -82,8 +82,8 @@ $ cordova create hello com.example.hello HelloWorld This creates the required directory structure for your cordova app. By default, the `cordova create` script generates a skeletal web-based application whose home page is the project's `www/index.html` file. ###See Also -- [Cordova create command reference documentation](../../cordova-cli/index.html#cordova-create-command) -- [Cordova project directory structure](../../cordova-cli/index.html#directory-structure) +- [Cordova create command reference documentation][cdv_create] +- [Cordova project directory structure][cdv_dir] ## Add Platforms @@ -117,7 +117,7 @@ in this directory are routinely overwritten when preparing applications for building, or when plugins are re-installed. ###See Also -- [Cordova platform command reference documentation](../../cordova-cli/index.html#cordova-platform-command) +- [Cordova platform command reference documentation][cdv_platform] ##Install pre-requrisites for building To build and run apps, you need to install SDKs for each platform you wish to target. Alternatively, if you are using browser for development you can use `browser` platform which does not require any platform SDKs. @@ -161,7 +161,7 @@ $ cordova build ios ``` ###See Also -- [Cordova build command reference documentation](../../dev/cordova-cli/index.html#cordova-build-command) +- [Cordova build command reference documentation][cdv_build] ##Test the App @@ -195,8 +195,8 @@ testing, following procedures that vary for each platform. ###See Also - [Setting up Android emulator](../../guide/platforms/android/index.html#setting-up-an-emulator) -- [Cordova run command reference documentation](../../cordova-cli/index.html#cordova-run-command) -- [Cordova emulate command reference documentation](../../cordova-cli/index.html#cordova-emulate-command) +- [Cordova run command reference documentation][cdv_run] +- [Cordova emulate command reference documentation][cdv_emulate] ## Add Plugins @@ -237,7 +237,7 @@ cordova-plugin-whitelist 1.2.1 "Whitelist" ``` ###See Also -- [Cordova plugin command reference documentation](../../cordova-cli/index.html#cordova-plugin-command) +- [Cordova plugin command reference documentation][cdv_plugin] - [Cordova plugin search page](/plugins/) - [Core Plugin APIs] @@ -316,6 +316,14 @@ $ cordova platform update ios --save ``` [DeviceReadyEvent]: ../../cordova/events/events.html#deviceready -[BackButtonEvent]: ../../cordova/events/events.html#backbutton -[CLI reference]: ../../cordova-cli/index.html +[BackButtonEvent]: ../../cordova/events/events.html#backbutton [Core Plugin APIs]: ../../guide/support/index.html#core-plugin-apis + +[CLI reference]: ../../reference/cordova-cli/index.html +[cdv_create]: ../../reference/cordova-cli/index.html#cordova-create-command +[cdv_dir]: ../../reference/cordova-cli/index.html#directory-structure +[cdv_platform]: ../../reference/cordova-cli/index.html#cordova-platform-command +[cdv_run]: ../../reference/cordova-cli/index.html#cordova-run-command +[cdv_emulate]: ../../reference/cordova-cli/index.html#cordova-emulate-command +[cdv_plugin]: ../../reference/cordova-cli/index.html#cordova-plugin-command +[cdv_build]: ../../reference/cordova-cli/index.html#cordova-build-command http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/4d62f605/www/docs/en/dev/guide/hybrid/plugins/index.md ---------------------------------------------------------------------- diff --git a/www/docs/en/dev/guide/hybrid/plugins/index.md b/www/docs/en/dev/guide/hybrid/plugins/index.md index 7459fbc..e1f3cd8 100644 --- a/www/docs/en/dev/guide/hybrid/plugins/index.md +++ b/www/docs/en/dev/guide/hybrid/plugins/index.md @@ -44,13 +44,12 @@ For each corresponding native interface, see the list at the end of this section. In addition to these instructions, when preparing to write a plugin it -is best to look over -[existing plugins](http://cordova.apache.org/contribute) +is best to look over [existing plugins](http://cordova.apache.org/contribute) for guidance. ## Building a Plugin -Application developers use the CLI's [plugin add command](../../../cordova-cli/index.html#cordova-plugin-add-command) to add a plugin to a project. The +Application developers use the CLI's [plugin add command][cdv_plugin] to add a plugin to a project. The argument to that command is the URL for a _git_ repository containing the plugin code. This example implements Cordova's Device API: @@ -245,3 +244,5 @@ For example, for a plugin that supports android, iOS & Windows, the keywords in ``` For more detailed example of a package.json, review the [package.json file of cordova-plugin-device](https://github.com/apache/cordova-plugin-device/blob/master/package.json). + +[cdv_plugin]: ../../../reference/cordova-cli/index.html#cordova-plugin-command http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/4d62f605/www/docs/en/dev/guide/platforms/android/index.md ---------------------------------------------------------------------- diff --git a/www/docs/en/dev/guide/platforms/android/index.md b/www/docs/en/dev/guide/platforms/android/index.md index 3580e04..5edd3cc 100644 --- a/www/docs/en/dev/guide/platforms/android/index.md +++ b/www/docs/en/dev/guide/platforms/android/index.md @@ -28,8 +28,8 @@ command-line tools in your development workflow. You need to install the Android SDK regardless of whether you want to use these platform-centered shell tools or cross-platform Cordova CLI for development. For a comparison of the two development paths, see the -[Overview](../../overview/index.html#development-paths). For details on the CLI, see [Cordova CLI Reference]. - +[Overview](../../overview/index.html#development-paths). For details on +the CLI, see [Cordova CLI Reference][cli_reference]. ## Requirements and Support @@ -156,7 +156,6 @@ reopen any command prompt windows after making changes to see them reflected C:\Development\android-sdk\tools ``` - ## Project Configuration ### Setting up an Emulator @@ -308,7 +307,7 @@ To sign an app, you need the following parameters: | Type of the Keystore | `--keystoreType` | *Default: auto-detect based on file extension*<br>Either pkcs12 or jks These parameters can be specified using the command line arguments above to -the [Cordova CLI](../../../cordova-cli/index.html) `build` or `run` commands. +the [Cordova CLI][cli_reference] `build` or `run` commands. __Note__: You should use double `--` to indicate that these are platform-specific arguments, for example: @@ -365,7 +364,6 @@ keyPassword=SECRET2 `storePassword` and `keyPassword` are optional, and will be prompted for if omitted. - ## Debugging For details on the debugging tools that come packaged with the Android SDK, see @@ -374,7 +372,6 @@ Additionally, Android's developer documentation for [debugging web apps](http:// provides an introduction for debugging the portion of your app running in the Webview. - ### Opening a Project in Android Studio Cordova for Android projects can be opened in the Android IDE, [Android Studio](http://developer.android.com/sdk/installing/index.html?pkg=studio). @@ -411,7 +408,6 @@ for more details.  - ## Platform Centered Workflow cordova-android includes a number of scripts that allow the platform to be used @@ -423,7 +419,7 @@ development path, you must still configure the Android SDK environment as described in [Requirements and Support](#requirements-and-support) above. -For each of the scripts discussed below, refer to [Cordova CLI Reference] for more information on their +For each of the scripts discussed below, refer to [Cordova CLI Reference][cli_reference] for more information on their arguments and usage. Each script has a name that matches the corresponding CLI command. For example, `cordova-android/bin/create` is equivalent to `cordova create`. @@ -452,7 +448,6 @@ To install plugins in this project, use the [Cordova Plugman Utility](../../../p Refer to [this](./upgrade.html) article for instructions to upgrade your `cordova-android` version. - ## Lifecycle Guide ### Cordova and Android @@ -755,4 +750,4 @@ on your device or emulator to simulate low memory scenarios. You should always do some amount of testing with this setting enabled to make sure that your application is properly maintaining state. -[Cordova CLI Reference]: ../../../cordova-cli/index.html +[cli_reference]: ../../../reference/cordova-cli/index.html http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/4d62f605/www/docs/en/dev/guide/platforms/blackberry10/index.md ---------------------------------------------------------------------- diff --git a/www/docs/en/dev/guide/platforms/blackberry10/index.md b/www/docs/en/dev/guide/platforms/blackberry10/index.md index 57e5c4a..0ce8760 100644 --- a/www/docs/en/dev/guide/platforms/blackberry10/index.md +++ b/www/docs/en/dev/guide/platforms/blackberry10/index.md @@ -30,7 +30,7 @@ For BlackBerry 10, you need to install the SDK regardless of whether you want to use the cross-platform Cordova CLI for development, or a narrower set of platform-centered command-line tools. For a comparison of the two development paths, see the [Overview](../../overview/index.html). For -details on each, see [Cordova CLI Reference] and the BlackBerry 10 +details on each, see [Cordova CLI Reference][cli] and the BlackBerry 10 Shell Tool Guide. ## Requirements @@ -145,7 +145,7 @@ $ blackberry-keytool -genkeypair -storepass <password> -author 'Your Nameâ ## Create a Project Use the `cordova` utility to set up a new project, as described in -[Cordova CLI Reference]. For example, in a source-code directory: +[Cordova CLI Reference][cli]. For example, in a source-code directory: ```bash $ cordova create hello com.example.hello @@ -294,4 +294,4 @@ Once the target is defined, you can provide it to the run command using $ cordova run blackberry10 --target=emu ``` -[Cordova CLI Reference]: ../../../cordova-cli/index.html +[cli]: ../../../reference/cordova-cli/index.html http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/4d62f605/www/docs/en/dev/guide/platforms/ios/index.md ---------------------------------------------------------------------- diff --git a/www/docs/en/dev/guide/platforms/ios/index.md b/www/docs/en/dev/guide/platforms/ios/index.md index 87653aa..997b9be 100644 --- a/www/docs/en/dev/guide/platforms/ios/index.md +++ b/www/docs/en/dev/guide/platforms/ios/index.md @@ -29,7 +29,7 @@ development workflow. You need to install the SDK tools regardless of whether you want to use these platform-centered shell tools or cross-platform Cordova CLI for development. For a comparison of the two development paths, see the [Overview](../../overview/index.html#development-paths). -For details on the CLI, see [Cordova CLI Reference]. +For details on the CLI, see [Cordova CLI Reference][cli]. ## Requirements and Support @@ -223,7 +223,7 @@ as described in [Requirements and Support](#link-requirements-and-support) above. For each of the scripts discussed below, refer to - [Cordova CLI Reference](../../../cordova-cli/index.html) for more information on their + [Cordova CLI Reference][cli] for more information on their arguments and usage. Each script has a name that matches the corresponding CLI command. For example, `cordova-ios/bin/create` is equivalent to `cordova create`. @@ -259,4 +259,4 @@ Refer to [this](./upgrade.html) article for instructions to upgrade your ```cord (Mac®, OS X®, Apple®, Xcode®, App Storeâ , iPad®, iPhone®, iPod® and Finder® are Trademarks of Apple Inc.) - [Cordova CLI Reference]: ../../../cordova-cli/index.html +[cli]: ../../../reference/cordova-cli/index.html http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/4d62f605/www/docs/en/dev/guide/support/index.md ---------------------------------------------------------------------- diff --git a/www/docs/en/dev/guide/support/index.md b/www/docs/en/dev/guide/support/index.md index d4e10a1..9ccfe0a 100644 --- a/www/docs/en/dev/guide/support/index.md +++ b/www/docs/en/dev/guide/support/index.md @@ -82,7 +82,7 @@ CLI's shorthand names. </tr> <tr> - <th><a href="../../cordova-plugin-device-motion/">Accelerometer</a></th> + <th><a href="../../reference/cordova-plugin-device-motion/">Accelerometer</a></th> <td data-col="android" class="y"></td> <td data-col="blackberry10" class="y"></td> <td data-col="ios" class="y"></td> @@ -92,7 +92,7 @@ CLI's shorthand names. </tr> <tr> - <th><a href="../../cordova-plugin-battery-status/">BatteryStatus</a></th> + <th><a href="../../reference/cordova-plugin-battery-status/">BatteryStatus</a></th> <td data-col="android" class="y"></td> <td data-col="blackberry10" class="y"></td> <td data-col="ios" class="y"></td> @@ -102,7 +102,7 @@ CLI's shorthand names. </tr> <tr> - <th><a href="../../cordova-plugin-camera/">Camera</a></th> + <th><a href="../../reference/cordova-plugin-camera/">Camera</a></th> <td data-col="android" class="y"></td> <td data-col="blackberry10" class="y"></td> <td data-col="ios" class="y"></td> @@ -112,7 +112,7 @@ CLI's shorthand names. </tr> <tr> - <th><a href="../../cordova-plugin-media-capture/">Capture</a></th> + <th><a href="../../reference/cordova-plugin-media-capture/">Capture</a></th> <td data-col="android" class="y"></td> <td data-col="blackberry10" class="y"></td> <td data-col="ios" class="y"></td> @@ -122,7 +122,7 @@ CLI's shorthand names. </tr> <tr> - <th><a href="../../cordova-plugin-device-orientation/">Compass</a></th> + <th><a href="../../reference/cordova-plugin-device-orientation/">Compass</a></th> <td data-col="android" class="y"></td> <td data-col="blackberry10" class="y"></td> <td data-col="ios" class="y">(3GS+)</td> @@ -132,7 +132,7 @@ CLI's shorthand names. </tr> <tr> - <th><a href="../../cordova-plugin-network-information/">Connection</a></th> + <th><a href="../../reference/cordova-plugin-network-information/">Connection</a></th> <td data-col="android" class="y"></td> <td data-col="blackberry10" class="y"></td> <td data-col="ios" class="y"></td> @@ -142,7 +142,7 @@ CLI's shorthand names. </tr> <tr> - <th><a href="../../cordova-plugin-contacts/">Contacts</a></th> + <th><a href="../../reference/cordova-plugin-contacts/">Contacts</a></th> <td data-col="android" class="y"></td> <td data-col="blackberry10" class="y"></td> <td data-col="ios" class="y"></td> @@ -152,7 +152,7 @@ CLI's shorthand names. </tr> <tr> - <th><a href="../../cordova-plugin-device/">Device</a></th> + <th><a href="../../reference/cordova-plugin-device/">Device</a></th> <td data-col="android" class="y"></td> <td data-col="blackberry10" class="y"></td> <td data-col="ios" class="y"></td> @@ -172,7 +172,7 @@ CLI's shorthand names. </tr> <tr> - <th><a href="../../cordova-plugin-file">File</a></th> + <th><a href="../../reference/cordova-plugin-file">File</a></th> <td data-col="android" class="y"></td> <td data-col="blackberry10" class="y"></td> <td data-col="ios" class="y"></td> @@ -182,7 +182,7 @@ CLI's shorthand names. </tr> <tr> - <th><a href="../../cordova-plugin-file-transfer/">File Transfer</a></th> + <th><a href="../../reference/cordova-plugin-file-transfer/">File Transfer</a></th> <td data-col="android" class="y"></td> <td data-col="blackberry10" class="y">* Do not support onprogress nor abort</td> <td data-col="ios" class="y"></td> @@ -192,7 +192,7 @@ CLI's shorthand names. </tr> <tr> - <th><a href="../../cordova-plugin-geolocation/">Geolocation</a></th> + <th><a href="../../reference/cordova-plugin-geolocation/">Geolocation</a></th> <td data-col="android" class="y"></td> <td data-col="blackberry10" class="y"></td> <td data-col="ios" class="y"></td> @@ -202,7 +202,7 @@ CLI's shorthand names. </tr> <tr> - <th><a href="../../cordova-plugin-globalization/">Globalization</a></th> + <th><a href="../../reference/cordova-plugin-globalization/">Globalization</a></th> <td data-col="android" class="y"></td> <td data-col="blackberry10" class="y"></td> <td data-col="ios" class="y"></td> @@ -212,7 +212,7 @@ CLI's shorthand names. </tr> <tr> - <th><a href="../../cordova-plugin-inappbrowser/">InAppBrowser</a></th> + <th><a href="../../reference/cordova-plugin-inappbrowser/">InAppBrowser</a></th> <td data-col="android" class="y"></td> <td data-col="blackberry10" class="y"></td> <td data-col="ios" class="y"></td> @@ -222,7 +222,7 @@ CLI's shorthand names. </tr> <tr> - <th><a href="../../cordova-plugin-media/">Media</a></th> + <th><a href="../../reference/cordova-plugin-media/">Media</a></th> <td data-col="android" class="y"></td> <td data-col="blackberry10" class="y"></td> <td data-col="ios" class="y"></td> @@ -232,7 +232,7 @@ CLI's shorthand names. </tr> <tr> - <th><a href="../../cordova-plugin-dialogs/">Notification</a></th> + <th><a href="../../reference/cordova-plugin-dialogs/">Notification</a></th> <td data-col="android" class="y"></td> <td data-col="blackberry10" class="y"></td> <td data-col="ios" class="y"></td> @@ -242,7 +242,7 @@ CLI's shorthand names. </tr> <tr> - <th><a href="../../cordova-plugin-splashscreen/">Splashscreen</a></th> + <th><a href="../../reference/cordova-plugin-splashscreen/">Splashscreen</a></th> <td data-col="android" class="y"></td> <td data-col="blackberry10" class="y"></td> <td data-col="ios" class="y"></td> @@ -252,7 +252,7 @@ CLI's shorthand names. </tr> <tr> - <th><a href="../../cordova-plugin-statusbar/">Status Bar</a></th> + <th><a href="../../reference/cordova-plugin-statusbar/">Status Bar</a></th> <td data-col="android" class="y"></td> <td data-col="blackberry10" class="n"></td> <td data-col="ios" class="y"></td> @@ -272,7 +272,7 @@ CLI's shorthand names. </tr> <tr> - <th><a href="../../cordova-plugin-vibration/">Vibration</a></th> + <th><a href="../../reference/cordova-plugin-vibration/">Vibration</a></th> <td data-col="android" class="y"></td> <td data-col="blackberry10" class="y"></td> <td data-col="ios" class="y"></td> --------------------------------------------------------------------- To unsubscribe, e-mail: commits-unsubscr...@cordova.apache.org For additional commands, e-mail: commits-h...@cordova.apache.org
