From 1fd86057c326dc4e848cbf2d9ff1c576a0c948bd Mon Sep 17 00:00:00 2001 From: Dave Gramlich Date: Tue, 21 Jul 2015 17:42:21 -0400 Subject: [PATCH] docs: pointed auth/faq docs to gcloud-common created a showdown extension for converting relative links localized showdown created markdown directive added deeplinking support --- docs/authorization.md | 28 +--------- docs/faq.md | 14 ++--- docs/index.html | 6 +- .../authorization/authorization.html | 7 ++- .../components/authorization/authorization.js | 5 +- .../components/contributing/contributing.html | 21 +++++++ .../components/contributing/contributing.js | 16 ++++++ docs/site/components/faq/faq.html | 5 +- docs/site/components/faq/faq.js | 5 +- .../components/markdown/markdown-directive.js | 41 ++++++++++++++ .../components/markdown/markdown-service.js | 55 +++++++++++++++++++ docs/site/components/subpage/subpage.html | 5 ++ .../troubleshooting/troubleshooting.html | 6 +- .../troubleshooting/troubleshooting.js | 5 +- docs/site/home.js | 2 + .../angular-markdown-directive/markdown.js | 36 ------------ docs/site/lib/highlight/highlight.min.js | 3 +- docs/site/lib/showdown/showdown.min.js | 3 + 18 files changed, 177 insertions(+), 86 deletions(-) create mode 100644 docs/site/components/contributing/contributing.html create mode 100644 docs/site/components/contributing/contributing.js create mode 100644 docs/site/components/markdown/markdown-directive.js create mode 100644 docs/site/components/markdown/markdown-service.js delete mode 100644 docs/site/lib/angular-markdown-directive/markdown.js create mode 100644 docs/site/lib/showdown/showdown.min.js diff --git a/docs/authorization.md b/docs/authorization.md index adb6da93ffe..1a9e149f7a7 100644 --- a/docs/authorization.md +++ b/docs/authorization.md @@ -1,30 +1,6 @@ -With `gcloud-node` it's incredibly easy to get authorized and start using Google's APIs. You can set your credentials on a global basis as well as on a per-API basis. See each individual API section below to see how you can auth on a per-API-basis. This is useful if you want to use different accounts for different Google Cloud services. - -## On Google Compute Engine - -If you are running this client on Google Compute Engine, we handle authorization for you with no configuration. You just need to make sure that when you [set up the GCE instance][gce-how-to], you add the correct scopes for the APIs you want to access. - -```hljs-class -var config = { - projectId: 'grape-spaceship-123' -}; +## With `gcloud-node` -var gcloud = require('gcloud')(config); -``` - -## Elsewhere - -If you are not running this client on Google Compute Engine, you need a Google Developers service account. To create a service account: - -1. Visit the [Google Developers Console][dev-console]. -2. Create a new project or click on an existing project. -3. Navigate to **APIs & auth** > **APIs section** and turn on the following APIs (you may need to enable billing in order to use these services): - * Google Cloud Datastore API - * Google Cloud Storage - * Google Cloud Storage JSON API -4. Navigate to **APIs & auth** > **Credentials** and then: - * If you want to use a new service account, click on **Create new Client ID** and select **Service account**. After the account is created, you will be prompted to download the JSON key file that the library uses to authorize your requests. - * If you want to generate a new key for an existing service account, click on **Generate new JSON key** and download the JSON key file. +With `gcloud-node` it's incredibly easy to get authorized and start using Google's APIs. You can set your credentials on a global basis as well as on a per-API basis. See each individual API section below to see how you can auth on a per-API-basis. This is useful if you want to use different accounts for different Google Cloud services. ```hljs-class var config = { diff --git a/docs/faq.md b/docs/faq.md index d7f2a32e907..e5aca93c52c 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -9,16 +9,12 @@ If you are not running this client on Google Compute Engine, you need a Google D 1. Visit the [Google Developers Console][dev-console]. 2. Create a new project or click on an existing project. 3. Navigate to **APIs & auth** > **APIs section** and turn on the following APIs (you may need to enable billing in order to use these services): - * Google Cloud Datastore API - * Google Cloud Storage - * Google Cloud Storage JSON API + * Google Cloud Datastore API + * Google Cloud Storage + * Google Cloud Storage JSON API 4. Navigate to **APIs & auth** > **Credentials** and then: - * If you want to use a new service account, click on **Create new Client ID** and select **Service account**. After the account is created, you will be prompted to download the JSON key file that the library uses to authorize your requests. - * If you want to generate a new key for an existing service account, click on **Generate new JSON key** and download the JSON key file. - -## What is the relationship between this and the `gcloud` command-line tool? - -Both this library and the `gcloud` command-line tool are a part of the Google Cloud SDK: a collection of tools and libraries that enable you to easily create and manage resources on the Google Cloud Platform. The `gcloud` command-line tool can be used to manage both your development workflow and your Google Cloud Platform resources while this is the Google Cloud Client Library for Node.js. + * If you want to use a new service account, click on **Create new Client ID** and select **Service account**. After the account is created, you will be prompted to download the JSON key file that the library uses to authorize your requests. + * If you want to generate a new key for an existing service account, click on **Generate new JSON key** and download the JSON key file. ## Does this replace [Google Cloud Node.js Client][googleapis]? diff --git a/docs/index.html b/docs/index.html index 79da1926cb1..ab91e64d5f4 100755 --- a/docs/index.html +++ b/docs/index.html @@ -26,11 +26,10 @@ - + - @@ -39,11 +38,14 @@ + + + + +
+
+
+
diff --git a/docs/site/components/contributing/contributing.js b/docs/site/components/contributing/contributing.js new file mode 100644 index 00000000000..073982b632a --- /dev/null +++ b/docs/site/components/contributing/contributing.js @@ -0,0 +1,16 @@ +angular + .module('gcloud.contributing', ['ngRoute', 'gcloud.subpage', 'gcloud.markdown']) + .config(function($routeProvider) { + 'use strict'; + + $routeProvider.when('/contributing', { + controller: 'ContributingCtrl', + templateUrl: 'site/components/contributing/contributing.html', + reloadOnSearch: false + }); + }) + + .controller('ContributingCtrl', function($scope) { + 'use strict'; + + }); diff --git a/docs/site/components/faq/faq.html b/docs/site/components/faq/faq.html index 91c56466502..0a6f9b34832 100644 --- a/docs/site/components/faq/faq.html +++ b/docs/site/components/faq/faq.html @@ -2,7 +2,7 @@
- Edit on GitHub @@ -15,7 +15,8 @@
- +
+
diff --git a/docs/site/components/faq/faq.js b/docs/site/components/faq/faq.js index 998d8899392..b8860725688 100644 --- a/docs/site/components/faq/faq.js +++ b/docs/site/components/faq/faq.js @@ -1,6 +1,6 @@ angular .module('gcloud.faq', [ - 'btford.markdown', + 'gcloud.markdown', 'ngRoute', 'gcloud.how-to-get-help', 'gcloud.subpage' @@ -10,7 +10,8 @@ angular $routeProvider.when('/faq', { controller: 'FaqCtrl', - templateUrl: 'site/components/faq/faq.html' + templateUrl: 'site/components/faq/faq.html', + reloadOnSearch: false }); }) diff --git a/docs/site/components/markdown/markdown-directive.js b/docs/site/components/markdown/markdown-directive.js new file mode 100644 index 00000000000..b07b005dad8 --- /dev/null +++ b/docs/site/components/markdown/markdown-directive.js @@ -0,0 +1,41 @@ +angular + .module('gcloud.markdown') + .directive('gcloudMarkdown', function (mdConverter, mdDeeplink, $http, $sce, $compile, $location, $window, $timeout) { + return { + retstrict: 'A', + link: function (scope, element, attrs) { + // could be cross domain, but that's ok! + var markdown = $sce.trustAsResourceUrl(attrs.gcloudMarkdown); + + // fetch markdown + $http.get(markdown).then(function (resp) { + var html, blocks; + + // make it pretty! + html = mdConverter.makeHtml(resp.data); + element.html(html); + blocks = element.find('pre').find('code'); + angular.forEach(blocks, hljs.highlightBlock); + + // this will trigger any directives inside the markdown + // e.g. "hljs-class" + $compile(element.contents())(scope); + + // wrapping in timeout to get around paint lag + $timeout(function () { + mdDeeplink($location.search().section) + }, 50); + }); + } + }; + }) + .directive('gcloudScroll', function (mdDeeplink, $location) { + return { + restrict: 'A', + link: function (scope, elem, attrs) { + elem.on('click', function (e) { + mdDeeplink(attrs.gcloudScroll); + }); + } + } + }); diff --git a/docs/site/components/markdown/markdown-service.js b/docs/site/components/markdown/markdown-service.js new file mode 100644 index 00000000000..f7ac4df88c1 --- /dev/null +++ b/docs/site/components/markdown/markdown-service.js @@ -0,0 +1,55 @@ +angular + .module('gcloud.markdown', []) + .config(function ($anchorScrollProvider) { + $anchorScrollProvider.disableAutoScrolling(); + }) + .factory('mdConverter', function ($location, $interpolate) { + var template = '{{text}}'; + var anchor = $interpolate(template); + + return new showdown.Converter({ + extensions: [function () { + return [{ + type: 'lang', + // unescaped version \[([^\]]+)\]\(([\/|\#][^)]+)\) + regex: '\\[([^\\]]+)\\]\\(([\\/|\\#][^)]+)\\)', + replace: function (match, text, href) { + var isDeeplink = /^\#/.test(href); + var data = { text: text }; + + if (isDeeplink) { + data.id = href.replace('#', ''); + data.href = $location.path() + '?section=' + data.id; + } else { + data.href = href.replace('readme.md', ''); + } + + return anchor(data); + } + }]; + }] + }); + }) + .factory('mdDeeplink', function ($window, $location) { + // retrieve amount to offset the scroll by (height of the page header) + function offset () { + if (!offset._value) { + var el = document.getElementsByClassName('page-header')[0]; + offset._value = el ? el.offsetHeight : 0; + } + + return offset._value; + } + + return function deeplink (section) { + if (!section) return; + // showdown doesn't insert hyphens like ghfm does + var id = section.split('-').join(''); + var el = document.getElementById(id); + + if (!el) return; + + $window.scrollTo(0, el.offsetTop - offset()); + }; + }); + diff --git a/docs/site/components/subpage/subpage.html b/docs/site/components/subpage/subpage.html index 20b6a8a7452..0fdab3f073f 100644 --- a/docs/site/components/subpage/subpage.html +++ b/docs/site/components/subpage/subpage.html @@ -72,6 +72,11 @@

Getting Started

Troubleshooting +
  • + + Contributing + +