From 9917742e143da88a8e6dd3e142a63e75a5dda88e Mon Sep 17 00:00:00 2001
From: Stephen Sawchuk <sawchuk@gmail.com>
Date: Thu, 9 Oct 2014 20:10:43 -0400
Subject: [PATCH] docs: re-structure versioning.

---
 docs/components/docs/docs-services.js | 35 +++++++++++++++++----------
 docs/components/docs/docs-values.js   | 33 ++++++++++++++++++++++---
 2 files changed, 52 insertions(+), 16 deletions(-)

diff --git a/docs/components/docs/docs-services.js b/docs/components/docs/docs-services.js
index e4dd9847722..f7de286e69d 100644
--- a/docs/components/docs/docs-services.js
+++ b/docs/components/docs/docs-services.js
@@ -1,24 +1,33 @@
 angular.module('gcloud.docs')
-  .factory('getLinks', function(pages) {
+  .factory('getLinks', function(versions, pages) {
     'use strict';
 
+    // `version` is the current version being browsed.
     return function(version) {
       var baseUrl = '#/docs/' + version;
       var VERSIONS = pages.VERSIONS;
-      var versions;
-      var match;
-      if (!version || version === 'master') {
-        versions = Object.keys(VERSIONS);
-        match = versions[versions.length - 1];
-      } else {
-        match = Object.keys(VERSIONS).filter(semver.satisfies.bind(null, version))[0];
+
+      if (version === 'master') {
+        // Use the most recent release.
+        version = versions[0];
       }
-      return VERSIONS[match]
-        .map(function(module) {
-          if (pages[module]._url) {
-            pages[module].url = pages[module]._url.replace('{baseUrl}', baseUrl);
+
+      // Use semver matching to put all matching modules together.
+      return Object.keys(VERSIONS)
+        .reduce(function(acc, potentialVersion) {
+          if (semver.satisfies(version, potentialVersion)) {
+            acc = acc.concat(VERSIONS[potentialVersion].map(function(module) {
+              if (pages[module]._url) {
+                pages[module].url = pages[module]._url.replace('{baseUrl}', baseUrl);
+              }
+              return pages[module];
+            }));
           }
-          return pages[module];
+          return acc;
+        }, [])
+        .sort(function(moduleA, moduleB) {
+          // A title matching `gcloud` will come first in the list.
+          return moduleA.title === 'gcloud' ? -1 : moduleA.title > moduleB.title;
         });
     };
   });
diff --git a/docs/components/docs/docs-values.js b/docs/components/docs/docs-values.js
index c785015e671..55e1a4b37cf 100644
--- a/docs/components/docs/docs-values.js
+++ b/docs/components/docs/docs-values.js
@@ -1,5 +1,20 @@
 angular.module('gcloud.docs')
   .value('pages', {
+
+    //---------------------------------------------
+    // Link schema:
+    //---------------------------------------------
+    // key: {
+    //   title: 'Display Name for Link',
+    //   _url: '{baseUrl}/module-name',
+    //
+    //   pages: [
+    //     title: 'Display Name for Sub-Page Link',
+    //     url: '/path-relevant-to-parent-url'
+    //   ]
+    // }
+    //---------------------------------------------
+
     gcloud: {
       title: 'gcloud',
       _url: '{baseUrl}'
@@ -62,8 +77,20 @@ angular.module('gcloud.docs')
     VERSIONS: {
       // Give a version with/without a comparator, anything semver:
       //   https://github.com/npm/node-semver#versions
-      // List should be in ascending order.
-      '<=0.7.1': ['gcloud', 'datastore', 'storage'],
-      '>0.7.1': ['gcloud', 'datastoreWithTransaction', 'pubsub', 'storage']
+      //
+      // Multiple keys may be used to match a version.
+      //
+      // Example:
+      // A user is browsing the docs for 0.7.0. If the list below contains the
+      // keys: "*", ">0.4.0", and "0.7.0", all of the contents will be joined.
+      //
+      // Notes on ordering:
+      // These are sorted alphabetically by `module`.title.
+      //
+      // To keep the documentation for the main module, `gcloud`, on top of the
+      // link list, **make sure the title is `gcloud`**
+      '*': ['gcloud', 'storage'],
+      '<0.8.0': ['datastore'],
+      '>=0.8.0': ['datastoreWithTransaction', 'pubsub']
     }
   });