diff --git a/docs/app/assets/css/docs.css b/docs/app/assets/css/docs.css index 6c8ce38387f5..839f6863741c 100644 --- a/docs/app/assets/css/docs.css +++ b/docs/app/assets/css/docs.css @@ -662,6 +662,11 @@ ul.events > li { max-width: 100%; } +.deprecation .title { + float: left; + margin-right: 5px; +} + @media only screen and (min-width: 769px) { [ng-include="partialPath"].ng-hide { display: block !important; diff --git a/docs/config/index.js b/docs/config/index.js index 4ec1423c65a0..03d02d702e33 100644 --- a/docs/config/index.js +++ b/docs/config/index.js @@ -52,10 +52,12 @@ module.exports = new Package('angularjs', [ .config(function(parseTagsProcessor) { + parseTagsProcessor.tagDefinitions.push(require('./tag-defs/deprecated')); // this will override the jsdoc version parseTagsProcessor.tagDefinitions.push(require('./tag-defs/tutorial-step')); parseTagsProcessor.tagDefinitions.push(require('./tag-defs/sortOrder')); parseTagsProcessor.tagDefinitions.push(require('./tag-defs/installation')); parseTagsProcessor.tagDefinitions.push(require('./tag-defs/this')); + }) @@ -65,7 +67,11 @@ module.exports = new Package('angularjs', [ .config(function(templateFinder, renderDocsProcessor, gitData) { - templateFinder.templateFolders.unshift(path.resolve(packagePath, 'templates')); + // We are completely overwriting the folders + templateFinder.templateFolders.length = 0; + templateFinder.templateFolders.unshift(path.resolve(packagePath, 'templates/examples')); + templateFinder.templateFolders.unshift(path.resolve(packagePath, 'templates/ngdoc')); + templateFinder.templateFolders.unshift(path.resolve(packagePath, 'templates/app')); renderDocsProcessor.extraData.git = gitData; }) diff --git a/docs/config/tag-defs/deprecated.js b/docs/config/tag-defs/deprecated.js new file mode 100644 index 000000000000..68545146fff3 --- /dev/null +++ b/docs/config/tag-defs/deprecated.js @@ -0,0 +1,42 @@ +'use strict'; + +var OPTION_MATCHER = /^\s*([\w-]+)="([^"]+)"\s+([\s\S]*)/; +var VALID_OPTIONS = ['sinceVersion', 'removeVersion']; + +module.exports = { + name: 'deprecated', + transforms: function(doc, tag, value) { + var result = {}; + var invalidOptions = []; + value = value.trim(); + while (OPTION_MATCHER.test(value)) { + value = value.replace(OPTION_MATCHER, function(_, key, value, rest) { + if (VALID_OPTIONS.indexOf(key) !== -1) { + result[key] = value; + } else { + invalidOptions.push(key); + } + return rest; + }); + } + if (invalidOptions.length > 0) { + throw new Error('Invalid options: ' + humanList(invalidOptions) + '. Value options are: ' + humanList(VALID_OPTIONS)); + } + result.description = value; + return result; + } +}; + +function humanList(values, sep, lastSep) { + if (sep === undefined) sep = ', '; + if (lastSep === undefined) lastSep = ' and '; + + return values.reduce(function(output, value, index, list) { + output += '"' + value + '"'; + switch (list.length - index) { + case 1: return output; + case 2: return output + lastSep; + default: return output + sep; + } + }, ''); +} diff --git a/docs/config/tag-defs/deprecated.spec.js b/docs/config/tag-defs/deprecated.spec.js new file mode 100644 index 000000000000..f95b2ea9e3bf --- /dev/null +++ b/docs/config/tag-defs/deprecated.spec.js @@ -0,0 +1,33 @@ +'use strict'; + +/* globals describe, it, expect */ +var tagDef = require('./deprecated'); + +describe('deprecated tag', function() { + describe('transforms', function() { + it('should return the trimmed value if no options', function() { + var tag = tagDef.transforms({}, {}, 'This is the description'); + expect(tag.description).toEqual('This is the description'); + }); + + it('should read options', function() { + var tag = tagDef.transforms({}, {}, ' sinceVersion="v1.3.4" removeVersion="v1.4.5" what is left is description'); + expect(tag.description).toEqual('what is left is description'); + expect(tag.sinceVersion).toEqual('v1.3.4'); + expect(tag.removeVersion).toEqual('v1.4.5'); + }); + + it('should cope with carriage returns', function() { + var tag = tagDef.transforms({}, {}, '\nsinceVersion="v1.3.4"\nremoveVersion="v1.4.5"\nwhat is left is description'); + expect(tag.description).toEqual('what is left is description'); + expect(tag.sinceVersion).toEqual('v1.3.4'); + expect(tag.removeVersion).toEqual('v1.4.5'); + }); + + it('should error if there is an invalid option', function() { + expect(function() { + tagDef.transforms({}, {}, ' fromVersion="v1.3.4" toVersion="v1.4.5" what is left is description'); + }).toThrowError('Invalid options: "fromVersion" and "toVersion". Value options are: "sinceVersion" and "removeVersion"'); + }); + }); +}); diff --git a/docs/config/templates/angular-service.template.js b/docs/config/templates/app/angular-service.template.js similarity index 100% rename from docs/config/templates/angular-service.template.js rename to docs/config/templates/app/angular-service.template.js diff --git a/docs/config/templates/error.template.html b/docs/config/templates/app/error.template.html similarity index 100% rename from docs/config/templates/error.template.html rename to docs/config/templates/app/error.template.html diff --git a/docs/config/templates/errorNamespace.template.html b/docs/config/templates/app/errorNamespace.template.html similarity index 100% rename from docs/config/templates/errorNamespace.template.html rename to docs/config/templates/app/errorNamespace.template.html diff --git a/docs/config/templates/indexPage.template.html b/docs/config/templates/app/indexPage.template.html similarity index 100% rename from docs/config/templates/indexPage.template.html rename to docs/config/templates/app/indexPage.template.html diff --git a/docs/config/templates/json-doc.template.json b/docs/config/templates/app/json-doc.template.json similarity index 100% rename from docs/config/templates/json-doc.template.json rename to docs/config/templates/app/json-doc.template.json diff --git a/docs/config/templates/nav-data.template.js b/docs/config/templates/app/nav-data.template.js similarity index 100% rename from docs/config/templates/nav-data.template.js rename to docs/config/templates/app/nav-data.template.js diff --git a/docs/config/templates/pages-data.template.js b/docs/config/templates/app/pages-data.template.js similarity index 100% rename from docs/config/templates/pages-data.template.js rename to docs/config/templates/app/pages-data.template.js diff --git a/docs/config/templates/tutorial.template.html b/docs/config/templates/app/tutorial.template.html similarity index 100% rename from docs/config/templates/tutorial.template.html rename to docs/config/templates/app/tutorial.template.html diff --git a/docs/config/templates/examples/index.template.html b/docs/config/templates/examples/index.template.html new file mode 100644 index 000000000000..986b3766e97c --- /dev/null +++ b/docs/config/templates/examples/index.template.html @@ -0,0 +1,21 @@ + + +
+ +Name | +Description | +
---|---|
{$ page.id | link(page.name, page) $} | +{$ page.description | firstParagraph | marked $} | +