Migrating to gcloud-common docs

[callmehiphop]

Fixes #710
Fixes #717

• Point to gcloud-common markdown files
  • Authorization
  • FAQs
  • Contributing (dependent on https://github.com/GoogleCloudPlatform/gcloud-common/pull/10)
• Update image markdown within gcloud-common - https://github.com/GoogleCloudPlatform/gcloud-common/pull/8
• Create angular directive to fix relative image paths
• Remove duplicate markdown content from local faq/auth - https://github.com/GoogleCloudPlatform/gcloud-common/pull/9
• Create Showdown extension for relative anchor tags
• Address markdown rendering errors - https://github.com/GoogleCloudPlatform/gcloud-common/pull/11 & Code blocks within lists do not render properly showdownjs/showdown#183
• Implement deeplinking

For your viewing pleasure: http://callmehiphop.github.io/gcloud-node-ghpages/#/docs/master

[callmehiphop]

@stephenplusplus Will we be deleting the authorization/faq markdown files within gcloud-node? It contains some information tailored to our library specifically, so I wasn't sure if wanted to have an additional auth link called something like "gcloud-node Authorization"

[jgeewax]

Maybe there's a way to append or inject more markdown into these at doc-generation time?

[callmehiphop]

It's just an angular directive, so we could include both on the same page and just trim the node specific one to remove any duplicated information.

[stephenplusplus]

For the images, we need to change gcloud-comon to use the ![](path.png) style. For some reason, I used <img>. After that, we have a few options, ranked by how good of a solution I think they are (please correct me if I'm wrong!)

1. Use absolute image paths in the gcloud-common markdown
2. Use a showdown extension to replace img paths with absolute urls at runtime
3. Use a directive to replace img paths with absolute urls at runtime

The extension would look like:

angular
  .module('gcloud.authorization', [/*...*/])
  .config(function($routeProvider, markdownConverterProvider) {
    'use strict';

    markdownConverterProvider.config({
      extensions: [function() {
        return [
          {
            type: 'output',
            regex: 'img src="',
            replace: 'img src="https://raw.githubusercontent.com/GoogleCloudPlatform/gcloud-common/master/authorization/'
          }
        ];
      }]
    });

  //...

The directive could look like:

angular
  .module('gcloud.detect-images', [])
  .directive('detectImages', function() {
    return function($scope, elem, attrs) {
      [].slice.call(elem.find('img')).forEach(function(img) {
        var src = img.getAttribute('src');
        img.setAttribute('src', attrs.detectImages + src);
      });
    };
  });

<btf-markdown
  highlight-markdown
  detect-images="https://raw.githubusercontent.com/GoogleCloudPlatform/gcloud-common/master/authorization/"
  ng-include="'https://raw.githubusercontent.com/GoogleCloudPlatform/gcloud-common/master/authorization/readme.md'">

[stephenplusplus]

For the Node-specific docs, I think we will have to add them after the common docs.

For Authorization, the common docs end with downloading a JSON key file. We can add on right after that to show how you use it with our library, and the transition should be easy. Same for FAQ, we can just tack any custom questions after the common ones.

It's not awesome to have a dependency on the wording of the docs, so I suppose we will just have to keep our docs in mind anytime the common docs change.

[jgeewax]

Yea - maybe a "gcloud-node specific auth" section?

[callmehiphop]

I ended up going with the directive option because:

• The hardcoded absolute URL feels gross to me and it might end up only being useful to us and not the other gcloud-* projects
• Configuring the provider doesn't promote re-use in case we need to do something similar for a different markdown file (e.g. we add images to faqs)

[callmehiphop]

So I put the node specific auth stuff back in and it looks pretty good, however the faqs are kinda ugly now. Ideally I think we would split the Where can I get more help? section into its own markdown file because it would be better placed at the end of the page. There were also some small formatting differences (h2s became h4s) so it's a little harder to distinguish between questions and answers since the text looks the same.

@stephenplusplus any opposition to making some minor changes to the common faq?

[stephenplusplus]

Change it up! We're the only ones implementing it so far (afaik), so let's
start with what works for us, and make changes as necessary as others join.
Also, we all share the same template, so it should be difficult to do
something for us that won't also benefit the others.

On Wednesday, July 22, 2015, Dave Gramlich notifications@github.com wrote:

So I put the node specific auth stuff back in and it looks pretty good,
however the faqs are kinda ugly now. Ideally I think we would split the Where
can I get more help? section into its own markdown file because it would
be better placed at the end of the page. There were also some small
formatting differences (h2s became h4s) so it's a little harder to
distinguish between questions and answers since the text looks the same.

Any opposition to making some minor changes to the common faq?

// cc @stephenplusplus https://github.com/stephenplusplus

—
Reply to this email directly or view it on GitHub
#734 (comment)
.

[stephenplusplus]

The hardcoded absolute URL feels gross to me and it might end up only being useful to us and not the other gcloud-* projects

I actually think it would help the other projects, since they should incorporate the live/master representation of gcloud-common in their docs instead of cloning locally. So, the image should always be remote, requiring an absolute path. Am I not considering something?

[callmehiphop]

If another project chose to use submodules over absolute URLs, it would kinda defeat the point of using submodules since the markdown files would be referencing an absolute image path instead of the relative one.

[stephenplusplus]

But I think if other projects used submodules, that would kind of defeat the point of the shared docs, since they would constantly have to be on the lookout for gcloud-common updates and manually do a submodule update and re-build of the site.

I know we have it easy, since we just point an Angular directive to a remote MD file, and boom, magic. But, for a site that doesn't have such an easy set-up, they will have to run some kind of MD -> HTML conversion as well, and the remote image will always work for everyone. Our docs are GitHub hosted and so are the -common images, so I think we should just be ¯_(ツ)_/¯ about it and use the absolute to dramatically simplify our site and wait to know it's a problem with others before making it harder on ourselves than it might need to be.

[stephenplusplus]

It looks so awesome. How should we handle the links inside of the common MD? Specifically, these ones are problematic:

Contributing

• If you encounter any difficulty during the process, do not hesitate to get in touch. (links to http://callmehiphop.github.io/troubleshooting/readme.md)
• If you've tried everything in our Troubleshooting guide... (links to http://callmehiphop.github.io/troubleshooting/readme.md)

[stephenplusplus]

Is it possible that the common links change from:

/troubleshooting/readme.md

to

/troubleshooting (if browsing on GH, the readme will still be displayed)

Then we can have a base href of http://googlecloudplatform.github.io/gcloud-node/#/?

[callmehiphop]

I think that would be a little bit tricky, <base> would mess with all of our dependency paths. Maybe for this one a Showdown plugin would be better?

[stephenplusplus]

Oh yeah, that makes more sense.