Skip to content

Commit

Permalink
docs: pointed auth/faq docs to gcloud-common
Browse files Browse the repository at this point in the history
created a showdown extension for converting relative links
localized showdown
created markdown directive
added deeplinking support
  • Loading branch information
callmehiphop committed Aug 5, 2015
1 parent 588faf8 commit 1fd8605
Show file tree
Hide file tree
Showing 18 changed files with 177 additions and 86 deletions.
28 changes: 2 additions & 26 deletions docs/authorization.md
Original file line number Diff line number Diff line change
@@ -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 = {
Expand Down
14 changes: 5 additions & 9 deletions docs/faq.md
Original file line number Diff line number Diff line change
Expand Up @@ -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]?

Expand Down
6 changes: 4 additions & 2 deletions docs/index.html
Original file line number Diff line number Diff line change
Expand Up @@ -26,11 +26,10 @@
<script src="//ajax.googleapis.com/ajax/libs/angularjs/1.2.23/angular.min.js"></script>
<script src="//code.angularjs.org/1.2.23/angular-route.min.js"></script>
<script src="//code.angularjs.org/1.2.23/angular-sanitize.min.js"></script>
<script src="//cdnjs.cloudflare.com/ajax/libs/showdown/0.3.1/showdown.min.js"></script>
<script src="site/lib/showdown/showdown.min.js"></script>
<script src="site/lib/highlight/highlight.min.js"></script>
<script src="site/lib/angular-highlightjs/angular-highlightjs.min.js"></script>
<script src="site/lib/node-semver/semver.browser.js"></script>
<script src="site/lib/angular-markdown-directive/markdown.js"></script>
<script src="site/lib/momentjs/moment.min.js"></script>
<script src="site/home.js"></script>
<script src="site/components/docs/docs.js"></script>
Expand All @@ -39,11 +38,14 @@
<script src="site/components/docs/docs-values.js"></script>
<script src="site/components/authorization/authorization.js"></script>
<script src="site/components/faq/faq.js"></script>
<script src="site/components/contributing/contributing.js"></script>
<script src="site/components/how-to-get-help/how-to-get-help-directive.js"></script>
<script src="site/components/language-switcher/language-switcher-directive.js"></script>
<script src="site/components/subpage/subpage-directive.js"></script>
<script src="site/components/header/header-directive.js"></script>
<script src="site/components/troubleshooting/troubleshooting.js"></script>
<script src="site/components/markdown/markdown-service.js"></script>
<script src="site/components/markdown/markdown-directive.js"></script>

<script>
(function() {
Expand Down
7 changes: 5 additions & 2 deletions docs/site/components/authorization/authorization.html
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
<header header title="Authorization">
<div class="row row--right">
<div class="col margin-vertical">
<a href="https://github.com/GoogleCloudPlatform/gcloud-node/edit/master/docs/authorization.md"
<a href="https://github.com/GoogleCloudPlatform/gcloud-common/edit/master/authorization/readme.md"
class="v-btn">
<img src="site/img/icon-link-github.svg" />
Edit on GitHub
Expand All @@ -15,5 +15,8 @@
<div subpage
header-templateUrl="authorization-header.html"
title="Authorization">
<btf-markdown highlight-markdown ng-include="'authorization.md'"></btf-markdown>
<div
gcloud-markdown="https://raw.githubusercontent.com/GoogleCloudPlatform/gcloud-common/master/authorization/readme.md">
</div>
<div gcloud-markdown="authorization.md"></div>
</div>
5 changes: 3 additions & 2 deletions docs/site/components/authorization/authorization.js
Original file line number Diff line number Diff line change
@@ -1,11 +1,12 @@
angular
.module('gcloud.authorization', ['ngRoute', 'gcloud.subpage', 'btford.markdown'])
.module('gcloud.authorization', ['ngRoute', 'gcloud.subpage', 'gcloud.markdown'])
.config(function($routeProvider) {
'use strict';

$routeProvider.when('/authorization', {
controller: 'AuthorizationCtrl',
templateUrl: 'site/components/authorization/authorization.html'
templateUrl: 'site/components/authorization/authorization.html',
reloadOnSearch: false
});
})

Expand Down
21 changes: 21 additions & 0 deletions docs/site/components/contributing/contributing.html
Original file line number Diff line number Diff line change
@@ -0,0 +1,21 @@
<script id="contributing-header.html" type="text/ng-template">
<header header title="Contributing">
<div class="row row--right">
<div class="col margin-vertical">
<a href="https://github.com/GoogleCloudPlatform/gcloud-common/edit/master/contributing/readme.md"
class="v-btn">
<img src="site/img/icon-link-github.svg" />
Edit on GitHub
</a>
</div>
</div>
</header>
</script>

<div subpage
header-templateUrl="contributing-header.html"
title="Contributing">
<div
gcloud-markdown="https://raw.githubusercontent.com/GoogleCloudPlatform/gcloud-common/master/contributing/readme.md">
</div>
</div>
16 changes: 16 additions & 0 deletions docs/site/components/contributing/contributing.js
Original file line number Diff line number Diff line change
@@ -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';

});
5 changes: 3 additions & 2 deletions docs/site/components/faq/faq.html
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
<header header title="FAQ">
<div class="row row--right">
<div class="col margin-vertical">
<a href="https://github.com/GoogleCloudPlatform/gcloud-node/edit/master/docs/faq.md"
<a href="https://github.com/GoogleCloudPlatform/gcloud-common/edit/master/faq/readme.md"
class="v-btn">
<img src="site/img/icon-link-github.svg" />
Edit on GitHub
Expand All @@ -15,7 +15,8 @@
<div subpage
header-templateUrl="faq-header.html"
title="FAQ">
<btf-markdown ng-include="'faq.md'"></btf-markdown>
<div gcloud-markdown="https://raw.githubusercontent.com/GoogleCloudPlatform/gcloud-common/master/faq/readme.md"></div>
<div gcloud-markdown="faq.md"></div>
<div how-to-get-help></div>
</div>

5 changes: 3 additions & 2 deletions docs/site/components/faq/faq.js
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
angular
.module('gcloud.faq', [
'btford.markdown',
'gcloud.markdown',
'ngRoute',
'gcloud.how-to-get-help',
'gcloud.subpage'
Expand All @@ -10,7 +10,8 @@ angular

$routeProvider.when('/faq', {
controller: 'FaqCtrl',
templateUrl: 'site/components/faq/faq.html'
templateUrl: 'site/components/faq/faq.html',
reloadOnSearch: false
});
})

Expand Down
41 changes: 41 additions & 0 deletions docs/site/components/markdown/markdown-directive.js
Original file line number Diff line number Diff line change
@@ -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);
});
}
}
});
55 changes: 55 additions & 0 deletions docs/site/components/markdown/markdown-service.js
Original file line number Diff line number Diff line change
@@ -0,0 +1,55 @@
angular
.module('gcloud.markdown', [])
.config(function ($anchorScrollProvider) {
$anchorScrollProvider.disableAutoScrolling();
})
.factory('mdConverter', function ($location, $interpolate) {
var template = '<a gcloud-scroll="{{id}}" href="#{{href}}">{{text}}</a>';
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());
};
});

5 changes: 5 additions & 0 deletions docs/site/components/subpage/subpage.html
Original file line number Diff line number Diff line change
Expand Up @@ -72,6 +72,11 @@ <h4 class="list-item--heading">Getting Started</h4>
Troubleshooting
</a>
</li>
<li>
<a href="#/contributing" ng-class="{ current: isActiveUrl('/contributing') }" title="Contributing">
Contributing
</a>
</li>
</ul>

<ul class="page-sections visible-lg">
Expand Down
6 changes: 4 additions & 2 deletions docs/site/components/troubleshooting/troubleshooting.html
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
<header header title="Troubleshooting">
<div class="row row--right">
<div class="col margin-vertical">
<a href="https://github.com/GoogleCloudPlatform/gcloud-node/edit/master/docs/troubleshooting.md"
<a href="https://github.com/GoogleCloudPlatform/gcloud-common/edit/master/troubleshooting/readme.md"
class="v-btn">
<img src="site/img/icon-link-github.svg" />
Edit on GitHub
Expand All @@ -15,6 +15,8 @@
<div subpage
header-templateUrl="troubleshooting-header.html"
title="Troubleshooting">
<btf-markdown ng-include="'troubleshooting.md'"></btf-markdown>
<div
gcloud-markdown="https://raw.githubusercontent.com/GoogleCloudPlatform/gcloud-common/master/troubleshooting/readme.md"></div>
<div gcloud-markdown="troubleshooting.md"></div>
<div how-to-get-help></div>
</div>
5 changes: 3 additions & 2 deletions docs/site/components/troubleshooting/troubleshooting.js
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
angular
.module('gcloud.troubleshooting', [
'btford.markdown',
'gcloud.markdown',
'ngRoute',
'gcloud.how-to-get-help',
'gcloud.subpage'
Expand All @@ -10,7 +10,8 @@ angular

$routeProvider.when('/troubleshooting', {
controller: 'TroubleshootingCtrl',
templateUrl: 'site/components/troubleshooting/troubleshooting.html'
templateUrl: 'site/components/troubleshooting/troubleshooting.html',
reloadOnSearch: false
});
})

Expand Down
2 changes: 2 additions & 0 deletions docs/site/home.js
Original file line number Diff line number Diff line change
Expand Up @@ -4,8 +4,10 @@ angular
'gcloud.authorization',
'gcloud.docs',
'gcloud.faq',
'gcloud.contributing',
'gcloud.language-switcher',
'gcloud.troubleshooting',
'gcloud.markdown',
'config',
'hljs'
])
Expand Down
36 changes: 0 additions & 36 deletions docs/site/lib/angular-markdown-directive/markdown.js

This file was deleted.

3 changes: 2 additions & 1 deletion docs/site/lib/highlight/highlight.min.js

Large diffs are not rendered by default.

3 changes: 3 additions & 0 deletions docs/site/lib/showdown/showdown.min.js

Large diffs are not rendered by default.

0 comments on commit 1fd8605

Please sign in to comment.