Repository: cordova-docs Updated Branches: refs/heads/master 0acfdce00 -> b65a9b0bc
CB-10552: Pull all the plugin docs to Cordova Pulling plugin docs to cordova Project: http://git-wip-us.apache.org/repos/asf/cordova-docs/repo Commit: http://git-wip-us.apache.org/repos/asf/cordova-docs/commit/0ae195a4 Tree: http://git-wip-us.apache.org/repos/asf/cordova-docs/tree/0ae195a4 Diff: http://git-wip-us.apache.org/repos/asf/cordova-docs/diff/0ae195a4 Branch: refs/heads/master Commit: 0ae195a472df0b000900cc26ee1d603d015aec55 Parents: 0acfdce Author: Sarangan Rajamanickam <[email protected]> Authored: Fri Feb 5 17:33:57 2016 -0800 Committer: Dmitry Blotsky <[email protected]> Committed: Mon Feb 15 13:49:35 2016 -0800 ---------------------------------------------------------------------- .gitignore | 1 + Makefile | 9 +- gulpfile.js | 9 +- tools/bin/fetch_docs.js | 143 +++++++++++++++++++ www/_data/fetched-files.yml | 153 +++++++++++++++++++++ www/_layouts/docs.html | 13 ++ www/docs/en/dev/cordova/plugins/pluginapis.md | 72 ++-------- 7 files changed, 334 insertions(+), 66 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/0ae195a4/.gitignore ---------------------------------------------------------------------- diff --git a/.gitignore b/.gitignore index 7850469..b89bc30 100644 --- a/.gitignore +++ b/.gitignore @@ -11,3 +11,4 @@ www/static/js/plugins.js node_modules Gemfile.lock +www/**/gen http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/0ae195a4/Makefile ---------------------------------------------------------------------- diff --git a/Makefile b/Makefile index 85703d9..0fe6f9d 100644 --- a/Makefile +++ b/Makefile @@ -36,6 +36,7 @@ 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 @@ -66,6 +67,7 @@ MAIN_CONFIG = $(CONFIG_DIR)/_config.yml DEV_CONFIG = $(CONFIG_DIR)/_dev.yml PROD_CONFIG = $(CONFIG_DIR)/_prod.yml DOCS_EXCLUDE_CONFIG = $(CONFIG_DIR)/_nodocs.yml +FETCH_CONFIG = $(DATA_DIR)/fetched-files.yml PLUGINS_SRC = $(PLUGINS_SRC_DIR)/app.js VERSION_FILE = VERSION @@ -129,7 +131,7 @@ help usage default: @echo " NODOCS: (defined or undefined) - excludes docs from build" @echo "" -data: $(TOC_FILES) $(DOCS_VERSION_DATA) +data: fetch $(TOC_FILES) $(DOCS_VERSION_DATA) configs: $(DEFAULTS_CONFIG) $(VERSION_CONFIG) styles: $(STYLES) plugins: $(PLUGINS_APP) @@ -157,6 +159,11 @@ 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) $(FETCH_DIR) + +fetch: $(FETCH_DIR) + # real targets # NOTE: # the ">>" operator appends to a file in both CMD and SH http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/0ae195a4/gulpfile.js ---------------------------------------------------------------------- diff --git a/gulpfile.js b/gulpfile.js index b31a5f4..67a3db8 100644 --- a/gulpfile.js +++ b/gulpfile.js @@ -35,6 +35,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 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"); @@ -53,6 +54,7 @@ var DOCS_VERSION_FILE = path.join(DATA_DIR, "docs-versions.yml"); var PLUGINS_FILE_NAME = "plugins.js"; var PLUGINS_FILE = path.join(JS_DIR, PLUGINS_FILE_NAME); var PLUGINS_SRC_FILE = path.join(PLUGINS_SRC_DIR, "app.js"); +var FETCH_CONFIG = path.join(DATA_DIR, "fetched-files.yml"); var BASE_CONFIGS = [CONFIG_FILE, DEFAULTS_CONFIG_FILE, VERSION_CONFIG_FILE]; var DEV_CONFIGS = [DEV_CONFIG_FILE]; @@ -153,6 +155,7 @@ gulp.task("help", function () { gutil.log(" data run all the below tasks"); gutil.log(" docs-versions create " + DOCS_VERSION_FILE); gutil.log(" toc create all generated ToC files in " + TOC_DIR); + gutil.log(" fetch download docs specified in " + FETCH_CONFIG); gutil.log(""); gutil.log(" styles run all the below tasks"); gutil.log(" less compile all .less files"); @@ -245,6 +248,10 @@ gulp.task("regen", ["jekyll"], function () { browsersync.reload(); }); +gulp.task("fetch", function (done) { + exec("node", [bin("fetch_docs.js"), FETCH_CONFIG, FETCH_DIR], done); +}); + gulp.task("reload", function () { browsersync.reload(); }); @@ -272,7 +279,7 @@ gulp.task("defaults", function () { .pipe(gulp.dest(ROOT_DIR)); }); -gulp.task("toc", function (done) { +gulp.task("toc", ["fetch"], function (done) { exec("node", [bin("toc.js"), DOCS_DIR, DATA_DIR], done); }); http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/0ae195a4/tools/bin/fetch_docs.js ---------------------------------------------------------------------- diff --git a/tools/bin/fetch_docs.js b/tools/bin/fetch_docs.js new file mode 100644 index 0000000..f91b33a --- /dev/null +++ b/tools/bin/fetch_docs.js @@ -0,0 +1,143 @@ +// 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 https = require("https"); +var path = require("path"); +var child_process = require("child_process"); +var yaml = require("js-yaml"); + +// constants +var DEFAULT_REPO_PATH = "README.md"; + +function generateFrontMatter (useDirectSrcURI, filePath, name, version) { + var obj = {}; + + if(useDirectSrcURI) { + var p = /https:\/\/raw.githubusercontent.com\/([^\/]+)\/([^\/]+)\/([^\/]+)\/(.+)/; + var filePathSplit = filePath.match(p); + name = filePathSplit[1] + "/" + filePathSplit[2]; + version = filePathSplit[3]; + filePath = filePathSplit.slice(4).join("/"); + } + + obj.edit_link = getRepoURIForFrontMatter(name, version, filePath); + obj.plugin_name = name; + obj.plugin_version = version; + + var frontMatter = "---\n" + yaml.dump(obj) + "\n---\n\n"; + return frontMatter; +} + +function getRepoFileURI (name, version, filePath) { + return "https://raw.githubusercontent.com/"; + name + "/" + version + "/" + filePath; +} + +function getRepoURIForFrontMatter (name, version, filePath) { + return "https://github.com/"; + name + "/blob/" + version + "/"+ filePath +} + +function getLatestRelease (packageName) { + var latestRelease = child_process.execSync("npm info " + packageName + " dist-tags.latest"); + return latestRelease.toString().trim(); +} + +function getPackageName (fileConfigSrc) { + return fileConfigSrc.packageName || fileConfigSrc.repoName.split('/')[1]; +} + +// 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); + } + + if (!fetchRoot) { + console.error("Please specify fetch root."); + process.exit(1); + } + + if (!fs.existsSync(configFile)) { + console.error("Config file doesn't exist."); + process.exit(); + } + + // ensure that the root for all fetched files exists + if (!fs.existsSync(fetchRoot)) { + fse.mkdirsSync(fetchRoot); + } + + // get config + var config = fs.readFileSync(configFile); + var fetchedFiles = yaml.load(config); + + // fetch all entries + fetchedFiles.forEach(function (fetchedFile) { + + if (!fetchedFile.dest) { + fetchedFile.dest = getPackageName(fetchedFile) + "/index.md"; + } + + var outFilePath = path.join(fetchRoot, fetchedFile.dest); + var outDirPath = path.dirname(outFilePath); + + var fileURI, frontMatter; + + if (typeof(fetchedFile.src) === "string") { + fileURI = fetchedFile.src; + frontMatter = generateFrontMatter(true, fileURI); + } else { + var packageName = getPackageName(fetchedFile.src); + var filePath = fetchedFile.src.path || DEFAULT_REPO_PATH; + + if (!fetchedFile.src.commit) { + fetchedFile.src.commit = getLatestRelease(packageName); + } + + fileURI = getRepoFileURI(fetchedFile.src.repoName, fetchedFile.src.commit, filePath); + frontMatter = generateFrontMatter(false, filePath, fetchedFile.src.repoName, fetchedFile.src.commit); + } + + // ensure that the output directory exists + if (!fs.existsSync(outDirPath)) { + fs.mkdirSync(outDirPath); + } + + console.log(fileURI + " -> " + outFilePath); + + var outFile = fs.createWriteStream(outFilePath); + outFile.write(frontMatter, function () { + + // open an HTTP request for the file + var request = https.get(fileURI, function (response) { + // write the response to the file + response.pipe(outFile); + }); + }); + }); // entries +} + +main(); http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/0ae195a4/www/_data/fetched-files.yml ---------------------------------------------------------------------- diff --git a/www/_data/fetched-files.yml b/www/_data/fetched-files.yml new file mode 100644 index 0000000..ab10e6c --- /dev/null +++ b/www/_data/fetched-files.yml @@ -0,0 +1,153 @@ +- + src: + repoName: "apache/cordova-cli" + packageName: "cordova" + path: "doc/bash.md" + dest: "cordova-cli/index.md" +- + src: + repoName: apache/cordova-plugin-battery-status + packageName: cordova-plugin-battery-status + displayName: Battery Status + description: Monitor the status of the device's battery. + dest: cordova-plugin-battery-status/index.md +- + src: + repoName: apache/cordova-plugin-camera + packageName: cordova-plugin-camera + displayName: Camera + description: Capture a photo using the device's camera. + dest: cordova-plugin-camera/index.md +- + src: + repoName: apache/cordova-plugin-console + packageName: cordova-plugin-console + displayName: Console + description: Add additional capability to console.log(). + dest: cordova-plugin-console/index.md +- + src: + repoName: apache/cordova-plugin-contacts + packageName: cordova-plugin-contacts + displayName: Contacts + description: Work with the devices contact database. + dest: cordova-plugin-contacts/index.md +- + src: + repoName: apache/cordova-plugin-device + packageName: cordova-plugin-device + displayName: Device + description: Gather device specific information. + dest: cordova-plugin-device/index.md +- + src: + repoName: apache/cordova-plugin-device-motion + packageName: cordova-plugin-device-motion + displayName: Device Motion (Accelerometer) + description: Tap into the device's motion sensor. + dest: cordova-plugin-device-motion/index.md +- + src: + repoName: apache/cordova-plugin-device-orientation + packageName: cordova-plugin-device-orientation + displayName: Device Orientation (Compass) + description: Obtain the direction that the device is pointing. + dest: cordova-plugin-device-orientation/index.md +- + src: + repoName: apache/cordova-plugin-dialogs + packageName: cordova-plugin-dialogs + displayName: Dialogs + description: Visual device notifications. + dest: cordova-plugin-dialogs/index.md +- + src: + repoName: apache/cordova-plugin-file + packageName: cordova-plugin-file + displayName: FileSystem + description: Hook into native file system through JavaScript. + dest: cordova-plugin-file/index.md +- + src: + repoName: apache/cordova-plugin-file-transfer + packageName: cordova-plugin-file-transfer + displayName: File Transfer + description: Hook into native file system through JavaScript. + dest: cordova-plugin-file-transfer/index.md +- + src: + repoName: apache/cordova-plugin-geolocation + packageName: cordova-plugin-geolocation + displayName: Geolocation + description: Make your application location aware. + dest: cordova-plugin-geolocation/index.md +- + src: + repoName: apache/cordova-plugin-globalization + packageName: cordova-plugin-globalization + displayName: Globalization + description: Enable representation of objects specific to a locale. + dest: cordova-plugin-globalization/index.md +- + src: + repoName: apache/cordova-plugin-inappbrowser + packageName: cordova-plugin-inappbrowser + displayName: InAppBrowser + description: Launch URLs in another in-app browser instance. + dest: cordova-plugin-inappbrowser/index.md +- + src: + repoName: apache/cordova-plugin-media + packageName: cordova-plugin-media + displayName: Media + description: Record and play back audio files. + dest: cordova-plugin-media/index.md +- + src: + repoName: apache/cordova-plugin-media-capture + packageName: cordova-plugin-media-capture + displayName: Media Capture + description: Capture media files using device's media capture applications. + dest: cordova-plugin-media-capture/index.md +- + src: + repoName: apache/cordova-plugin-network-information + packageName: cordova-plugin-network-information + displayName: Network Information (Connection) + description: Quickly check the network state, and cellular network information. + dest: cordova-plugin-network-information/index.md +- + src: + repoName: apache/cordova-plugin-splashscreen + packageName: cordova-plugin-splashscreen + displayName: Splashscreen + description: Show and hide the applications splash screen. + dest: cordova-plugin-splashscreen/index.md +- + src: + repoName: apache/cordova-plugin-vibration + packageName: cordova-plugin-vibration + displayName: Vibration + description: An API to vibrate the device. + dest: cordova-plugin-vibration/index.md +- + src: + repoName: apache/cordova-plugin-statusbar + packageName: cordova-plugin-statusbar + displayName: StatusBar + description: An API for showing, hiding and configuring status bar background. + dest: cordova-plugin-statusbar/index.md +- + src: + repoName: apache/cordova-plugin-whitelist + packageName: cordova-plugin-whitelist + displayName: Whitelist + description: A plugin to whitelist network requests. Must install to have any network requests in your applications. + dest: cordova-plugin-whitelist/index.md +- + src: + repoName: apache/cordova-plugin-legacy-whitelist + packageName: cordova-plugin-legacy-whitelist + displayName: Legacy Whitelist + description: A plugin to use the old style of whitelist before it was ripped out and changed in the whitelist plugin. + dest: cordova-plugin-legacy-whitelist/index.md \ No newline at end of file http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/0ae195a4/www/_layouts/docs.html ---------------------------------------------------------------------- diff --git a/www/_layouts/docs.html b/www/_layouts/docs.html index 4af2ec8..0439df5 100644 --- a/www/_layouts/docs.html +++ b/www/_layouts/docs.html @@ -183,6 +183,19 @@ analytics_id: UA-64283057-1 {% endif %} + {% if page.plugin_name and page.plugin_version %} + <div class="alert alert-warning docs-alert" role="alert"> + <button type="button" class="close" data-dismiss="alert" aria-label="Close"> + <span aria-hidden="true">×</span> + </button> + This documentation is for the version: {{ page.plugin_name }}:{{ page.plugin_version }}. + <a href="https://github.com/{{ page.plugin_name }}/releases"> + Visit Github for other versions. + </a> + </div> + + {% endif %} + <div id="page-toc-source"> {{ content }} </div> http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/0ae195a4/www/docs/en/dev/cordova/plugins/pluginapis.md ---------------------------------------------------------------------- diff --git a/www/docs/en/dev/cordova/plugins/pluginapis.md b/www/docs/en/dev/cordova/plugins/pluginapis.md index 70ee6fe..65f6778 100644 --- a/www/docs/en/dev/cordova/plugins/pluginapis.md +++ b/www/docs/en/dev/cordova/plugins/pluginapis.md @@ -28,69 +28,13 @@ You can search through all existing plugins (including third-party plugins) on [ The traditional set of core Cordova plugins are as follows: -- [Battery Status](https://www.npmjs.com/package/cordova-plugin-battery-status) -> Monitor the status of the device's battery. - -- [Camera](https://www.npmjs.com/package/cordova-plugin-camera) -> Capture a photo using the device's camera. - -- [Console](https://www.npmjs.com/package/cordova-plugin-console) -> Add additional capability to console.log(). - -- [Contacts](https://www.npmjs.com/package/cordova-plugin-contacts) -> Work with the devices contact database. - -- [Device](https://www.npmjs.com/package/cordova-plugin-device) -> Gather device specific information. - -- [Device Motion (Accelerometer)](https://www.npmjs.com/package/cordova-plugin-device-motion) -> Tap into the device's motion sensor. - -- [Device Orientation (Compass)](https://www.npmjs.com/package/cordova-plugin-device-orientation) -> Obtain the direction that the device is pointing. - -- [Dialogs](https://www.npmjs.com/package/cordova-plugin-dialogs) -> Visual device notifications. - -- [FileSystem](https://www.npmjs.com/package/cordova-plugin-file) -> Hook into native file system through JavaScript. - -- [File Transfer](https://www.npmjs.com/package/cordova-plugin-file-transfer) -> Hook into native file system through JavaScript. - -- [Geolocation](https://www.npmjs.com/package/cordova-plugin-geolocation) -> Make your application location aware. - -- [Globalization](https://www.npmjs.com/package/cordova-plugin-globalization) -> Enable representation of objects specific to a locale. - -- [InAppBrowser](https://www.npmjs.com/package/cordova-plugin-inappbrowser) -> Launch URLs in another in-app browser instance. - -- [Media](https://www.npmjs.com/package/cordova-plugin-media) -> Record and play back audio files. - -- [Media Capture](https://www.npmjs.com/package/cordova-plugin-media-capture) -> Capture media files using device's media capture applications. - -- [Network Information (Connection)](https://www.npmjs.com/package/cordova-plugin-network-information) -> Quickly check the network state, and cellular network information. - -- [Splashscreen](https://www.npmjs.com/package/cordova-plugin-splashscreen) -> Show and hide the applications splash screen. - -- [Vibration](https://www.npmjs.com/package/cordova-plugin-vibration) -> An API to vibrate the device. - -- [StatusBar](https://www.npmjs.com/package/cordova-plugin-statusbar) -> An API for showing, hiding and configuring status bar background. - -- [Whitelist](https://www.npmjs.com/package/cordova-plugin-whitelist) -> A plugin to whitelist network requests. Must install to have any network requests in your applications. - -- [Legacy Whitelist](https://www.npmjs.com/package/cordova-plugin-legacy-whitelist) -> A plugin to use the old style of whitelist before it was ripped out and changed in the whitelist plugin. - - +{% for fileSpec in site.data.fetched-files %} +{% if fileSpec.src.repoName contains "cordova-plugin" %} + {% assign repoSplit = fileSpec.src.repoName | split:'/' %} + {% capture packageName %}{% if fileSpec.src.packageName %}{{ fileSpec.src.packageName }}{% else %}{{ repoSplit[1] }}{% endif %}{% endcapture %} +- [{{ fileSpec.src.displayName }}](../../gen/{{ packageName }}/) +> {{ fileSpec.src.description }} +{% endif %} +{% endfor %} Non-English translations of these plugin docs can be found by going to the plugin github repos and looking in the docs folder --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
