From 46dfb92afd185c93f60ca90a72653f33d7cb18e8 Mon Sep 17 00:00:00 2001 From: Matias Niemelä Date: Thu, 13 Jun 2013 22:37:13 -0400 Subject: feat(ngdocs): provide support for user to jump between different versions of the angularjs documentation --- docs/src/appCache.js | 2 +- docs/src/gen-docs.js | 10 +++- docs/src/ngdoc.js | 19 +++++++ docs/src/templates/css/docs.css | 4 ++ docs/src/templates/index.html | 123 +++++++++++++++++++++------------------- docs/src/templates/js/docs.js | 66 +++++++++++++++++++-- 6 files changed, 160 insertions(+), 64 deletions(-) (limited to 'docs/src') diff --git a/docs/src/appCache.js b/docs/src/appCache.js index 7b21624e..01551f2b 100644 --- a/docs/src/appCache.js +++ b/docs/src/appCache.js @@ -61,7 +61,7 @@ function appCacheTemplate() { "syntaxhighlighter/syntaxhighlighter-combined.js", "../angular.min.js", "docs-combined.js", - "docs-keywords.js", + "docs-data.js", "docs-combined.css", "syntaxhighlighter/syntaxhighlighter-combined.css", "img/texture_1.png", diff --git a/docs/src/gen-docs.js b/docs/src/gen-docs.js index 52d1f629..f8ca5548 100755 --- a/docs/src/gen-docs.js +++ b/docs/src/gen-docs.js @@ -43,6 +43,8 @@ writer.makeDir('build/docs/', true).then(function() { function writeTheRest(writesFuture) { var metadata = ngdoc.metadata(docs); + var versions = ngdoc.ngVersions(); + var currentVersion = ngdoc.ngCurrentVersion(); writesFuture.push(writer.symlink('../../docs/content/notes', 'build/docs/notes', 'dir')); writesFuture.push(writer.symlinkTemplate('css', 'dir')); @@ -90,8 +92,12 @@ function writeTheRest(writesFuture) { writesFuture.push(writer.copyTemplate('docs-scenario.html')); // will be rewritten, don't symlink writesFuture.push(writer.output('docs-scenario.js', ngdoc.scenarios(docs))); - writesFuture.push(writer.output('docs-keywords.js', - ['NG_PAGES=', JSON.stringify(metadata).replace(/{/g, '\n{'), ';'])); + writesFuture.push(writer.output('docs-data.js',[ + "angular.module('docsData', [])", + ".value('NG_PAGES'," + JSON.stringify(metadata).replace(/{/g, '\n{') + ")", + ".value('NG_VERSION'," + JSON.stringify(currentVersion) + ")", + ".value('NG_VERSIONS'," + JSON.stringify(versions) + ");" + ])); writesFuture.push(writer.output('sitemap.xml', new SiteMap(docs).render())); writesFuture.push(writer.output('robots.txt', 'Sitemap: http://docs.angularjs.org/sitemap.xml\n')); diff --git a/docs/src/ngdoc.js b/docs/src/ngdoc.js index 1870f87c..af78c1e3 100644 --- a/docs/src/ngdoc.js +++ b/docs/src/ngdoc.js @@ -11,6 +11,8 @@ var globalID = 0; var fs = require('fs'); var fspath = require('path'); var markdown = new Showdown.converter({ extensions : ['table'] }); +var shell = require('shelljs'); +var gruntUtil = require('../../lib/grunt/utils.js'); exports.trim = trim; exports.metadata = metadata; @@ -18,6 +20,23 @@ exports.scenarios = scenarios; exports.merge = merge; exports.Doc = Doc; +exports.ngVersions = function() { + var line, versions = [], regex = /^v([1-9]\d*(?:\.\d+)+)$/; //only fetch >= 1.0.0 versions + shell.exec('git tag', {silent: true}).output.split(/\s*\n\s*/) + .forEach(function(line) { + var matches = regex.exec(line); + if(matches && matches.length > 0) { + versions.push(matches[1]); + } + }); + versions.push(exports.ngCurrentVersion().number); + return versions; +}; + +exports.ngCurrentVersion = function() { + return gruntUtil.getVersion(); +}; + var BOOLEAN_ATTR = {}; ['multiple', 'selected', 'checked', 'disabled', 'readOnly', 'required'].forEach(function(value) { BOOLEAN_ATTR[value] = true; diff --git a/docs/src/templates/css/docs.css b/docs/src/templates/css/docs.css index 1b87c551..6977d205 100644 --- a/docs/src/templates/css/docs.css +++ b/docs/src/templates/css/docs.css @@ -461,4 +461,8 @@ pre ol li { box-shadow:-6px 0 5px #555; display:block; border-radius:10px; + +.docs-version-jump { + width:180px; + margin-bottom:20px; } diff --git a/docs/src/templates/index.html b/docs/src/templates/index.html index 8e2fbc37..15093d4c 100644 --- a/docs/src/templates/index.html +++ b/docs/src/templates/index.html @@ -48,8 +48,8 @@ addTag('script', {src: 'components/google-code-prettify.js' }, sync); addTag('script', {src: 'components/' + (debug ? 'lunr.js' : 'lunr.min.js') }, sync); addTag('script', {src: 'components/' + (debug ? 'showdown.js' : 'showdown.min.js') }, sync); + addTag('script', {src: 'docs-data.js'}, sync); addTag('script', {src: 'js/docs.js'}, sync); - addTag('script', {src: 'docs-keywords.js'}, sync); function path(name) { if (production) { @@ -233,74 +233,83 @@
-
-
- - +
+
+
+ +
+ + +
-
-
Filtered results:
+
+
Filtered results:
- + - - + +
diff --git a/docs/src/templates/js/docs.js b/docs/src/templates/js/docs.js index 97fea067..ae0f1e58 100644 --- a/docs/src/templates/js/docs.js +++ b/docs/src/templates/js/docs.js @@ -4,6 +4,64 @@ var docsApp = { serviceFactory: {} }; +docsApp.controller.DocsVersionsCtrl = ['$scope', '$window', 'NG_VERSIONS', function($scope, $window, NG_VERSIONS) { + $scope.versions = expandVersions(NG_VERSIONS); + $scope.version = ($scope.version || angular.version.full).match(/^([\d\.]+\d+)/)[1]; //match only the number + + $scope.jumpToDocsVersion = function(value) { + var isLastStable, + version, + versions = $scope.versions; + for(var i=versions.length-1;i>=0;i--) { + var v = versions[i]; + if(v.version == value) { + var next = versions[i - 1]; + isLastStable = v.stable && (!next || next && !next.stable); + version = v; + break; + } + }; + + if(version && version.version >= '1.0.0') { + //the older versions have a different path to the docs within their repo directory + var docsPath = version.version < '1.0.2' ? 'docs-' + version.version : 'docs'; + + //the last stable version should redirect to docs.angularjs.org instead of code.angularjs.org + var url = 'http://' + + (isLastStable ? + 'docs.angularjs.org' : + 'code.angularjs.org/' + version.version + '/' + docsPath); + + $window.location = url; + } + }; + + function expandVersions(angularVersions) { + var unstableVersionStart = 0; + angularVersions.forEach(function(version) { + var split = version.split('.'); + unstableVersionStart = split[1] % 2 == 1 ? + Math.max(unstableVersionStart, parseInt(split[0] + '' + split[1])) : + unstableVersionStart; + }); + + var versions = []; + for(var i=angularVersions.length-1;i>=0;i--) { + var version = angularVersions[i]; + var split = version.split('.'); + var stable = parseInt(split[0] + '' + split[1]) < unstableVersionStart; + versions.push({ + version : version, + stable : stable, + title : 'AngularJS - v' + version, + group : (stable ? 'Stable' : 'Unstable') + }); + }; + + return versions; + }; +}]; + docsApp.controller.DocsNavigationCtrl = ['$scope', 'fullTextSearch', '$location', function($scope, fullTextSearch, $location) { fullTextSearch.init(); $scope.search = function(q) { @@ -47,7 +105,7 @@ docsApp.controller.DocsNavigationCtrl = ['$scope', 'fullTextSearch', '$location' }; }]; -docsApp.serviceFactory.fullTextSearch = ['$q', '$rootScope', function($q, $rootScope) { +docsApp.serviceFactory.fullTextSearch = ['$q', '$rootScope', 'NG_PAGES', function($q, $rootScope, NG_PAGES) { return { dbName : 'docs', indexName : 'docsindex', @@ -374,7 +432,7 @@ docsApp.serviceFactory.openJsFiddle = function(templateMerge, formPostData, angu }; -docsApp.serviceFactory.sections = function sections() { +docsApp.serviceFactory.sections = ['NG_PAGES', function sections(NG_PAGES) { var sections = { guide: [], api: [], @@ -407,7 +465,7 @@ docsApp.serviceFactory.sections = function sections() { }); return sections; -}; +}]; docsApp.controller.DocsController = function($scope, $location, $window, $cookies, sections) { @@ -706,7 +764,7 @@ docsApp.controller.DocsController = function($scope, $location, $window, $cookie }; -angular.module('docsApp', ['ngResource', 'ngRoute', 'ngCookies', 'ngSanitize', 'bootstrap', 'bootstrapPrettify']). +angular.module('docsApp', ['ngResource', 'ngRoute', 'ngCookies', 'ngSanitize', 'bootstrap', 'bootstrapPrettify', 'docsData']). config(function($locationProvider) { $locationProvider.html5Mode(true).hashPrefix('!'); }). -- cgit v1.2.3