From 8be7b5d125d3f584824066b014448029b55a2dcd Mon Sep 17 00:00:00 2001 From: Peter Bacon Darwin Date: Mon, 15 Sep 2014 20:33:58 +0100 Subject: [PATCH 1/8] chore(docs): update to dgeni-0.4.0 * update package with new services and computeId config * generateIndexPagesProcessor was not using log * use StringMap not ES6-shim Map in errorNamespaceMap * remove unused dependencies from generateErrorDocsProcessor * ensure generatePagesDataProcessor adds its doc to the collection * debugDumpProcessor was moved to dgeni-packages --- docs/config/index.js | 173 ++++++-- docs/config/inline-tag-defs/type.js | 25 +- docs/config/processors/debug-dump.js | 33 -- docs/config/processors/error-docs.js | 103 +++-- docs/config/processors/git-data.js | 20 - docs/config/processors/index-page.js | 67 ++-- docs/config/processors/keywords.js | 106 ++--- docs/config/processors/pages-data.js | 326 +++++++-------- docs/config/processors/protractor-generate.js | 50 --- docs/config/processors/versions-data.js | 62 ++- docs/config/services/deployments/debug.js | 39 ++ docs/config/services/deployments/default.js | 39 ++ docs/config/services/deployments/jquery.js | 43 ++ .../config/services/deployments/production.js | 42 ++ docs/config/services/errorNamespaceMap.js | 10 + docs/config/services/getMinerrInfo.js | 15 + docs/config/services/getVersion.js | 17 + docs/config/services/gitData.js | 17 + .../templates/protractorTests.template.js | 10 - .../templates/runnableExample.template.html | 9 +- docs/docs.config.js | 188 --------- docs/gulpfile.js | 11 +- npm-shrinkwrap.json | 373 ++++++------------ package.json | 4 +- scripts/travis/build.sh | 7 +- 25 files changed, 861 insertions(+), 928 deletions(-) delete mode 100644 docs/config/processors/debug-dump.js delete mode 100644 docs/config/processors/git-data.js delete mode 100644 docs/config/processors/protractor-generate.js create mode 100644 docs/config/services/deployments/debug.js create mode 100644 docs/config/services/deployments/default.js create mode 100644 docs/config/services/deployments/jquery.js create mode 100644 docs/config/services/deployments/production.js create mode 100644 docs/config/services/errorNamespaceMap.js create mode 100644 docs/config/services/getMinerrInfo.js create mode 100644 docs/config/services/getVersion.js create mode 100644 docs/config/services/gitData.js delete mode 100644 docs/config/templates/protractorTests.template.js delete mode 100644 docs/docs.config.js diff --git a/docs/config/index.js b/docs/config/index.js index 84386df2e63c..0f71cb54c1ce 100644 --- a/docs/config/index.js +++ b/docs/config/index.js @@ -1,44 +1,153 @@ -var _ = require('lodash'); +"use strict"; + var path = require('canonical-path'); var packagePath = __dirname; -var basePackage = require('dgeni-packages/ngdoc'); -var examplesPackage = require('dgeni-packages/examples'); +var Package = require('dgeni').Package; + +// Create and export a new Dgeni package called dgeni-example. This package depends upon +// the jsdoc and nunjucks packages defined in the dgeni-packages npm module. +module.exports = new Package('angularjs', [ + require('dgeni-packages/ngdoc'), + require('dgeni-packages/nunjucks'), + require('dgeni-packages/examples') +]) + + +.factory(require('./services/errorNamespaceMap')) +.factory(require('./services/getMinerrInfo')) +.factory(require('./services/getVersion')) +.factory(require('./services/gitData')) + +.factory(require('./services/deployments/debug')) +.factory(require('./services/deployments/default')) +.factory(require('./services/deployments/jquery')) +.factory(require('./services/deployments/production')) + +.factory(require('./inline-tag-defs/type')) + + +.processor(require('./processors/error-docs')) +.processor(require('./processors/index-page')) +.processor(require('./processors/keywords')) +.processor(require('./processors/pages-data')) +.processor(require('./processors/versions-data')) + + +.config(function(dgeni, log, readFilesProcessor, writeFilesProcessor) { + + dgeni.stopOnValidationError = true; + dgeni.stopOnProcessingError = true; + + log.level = 'info'; + + readFilesProcessor.basePath = path.resolve(__dirname,'../..'); + readFilesProcessor.sourceFiles = [ + { include: 'src/**/*.js', basePath: 'src' }, + { include: 'docs/content/**/*.ngdoc', basePath: 'docs/content' } + ]; + + writeFilesProcessor.outputFolder = 'build/docs'; + +}) + + +.config(function(parseTagsProcessor) { + parseTagsProcessor.tagDefinitions.push(require('./tag-defs/tutorial-step')); + parseTagsProcessor.tagDefinitions.push(require('./tag-defs/sortOrder')); +}) + + +.config(function(inlineTagProcessor, typeInlineTagDef) { + inlineTagProcessor.inlineTagDefinitions.push(typeInlineTagDef); +}) + + +.config(function(templateFinder, renderDocsProcessor, gitData) { + templateFinder.templateFolders.unshift(path.resolve(packagePath, 'templates')); + renderDocsProcessor.extraData.git = gitData; +}) + + +.config(function(computePathsProcessor, computeIdsProcessor) { + + computePathsProcessor.pathTemplates.push({ + docTypes: ['error'], + pathTemplate: 'error/${namespace}/${name}', + outputPathTemplate: 'partials/error/${namespace}/${name}.html' + }); + + computePathsProcessor.pathTemplates.push({ + docTypes: ['errorNamespace'], + pathTemplate: 'error/${name}', + outputPathTemplate: 'partials/error/${name}.html' + }); + + computePathsProcessor.pathTemplates.push({ + docTypes: ['overview', 'tutorial'], + getPath: function(doc) { + var docPath = path.dirname(doc.fileInfo.relativePath); + if ( doc.fileInfo.baseName !== 'index' ) { + docPath = path.join(docPath, doc.fileInfo.baseName); + } + return docPath; + }, + getOutputPath: function(doc) { + return 'partials/' + doc.path + + ( doc.fileInfo.baseName === 'index' ? '/index.html' : '.html'); + } + }); + + computePathsProcessor.pathTemplates.push({ + docTypes: ['e2e-test'], + getPath: function() {}, + outputPathTemplate: 'ptore2e/${example.id}/${deployment.name}_test.js' + }); -module.exports = function(config) { + computePathsProcessor.pathTemplates.push({ + docTypes: ['indexPage'], + getPath: function() {}, + outputPathTemplate: '${id}.html' + }); - config = basePackage(config); - config = examplesPackage(config); - config.append('processing.processors', [ - require('./processors/git-data'), - require('./processors/error-docs'), - require('./processors/keywords'), - require('./processors/versions-data'), - require('./processors/pages-data'), - require('./processors/protractor-generate'), - require('./processors/index-page'), - require('./processors/debug-dump') - ]); + computeIdsProcessor.idTemplates.push({ + docTypes: ['overview', 'tutorial', 'e2e-test', 'indexPage'], + getId: function(doc) { return doc.fileInfo.baseName; }, + getAliases: function(doc) { return [doc.id]; } + }); - config.append('processing.tagDefinitions', [ - require('./tag-defs/tutorial-step'), - require('./tag-defs/sortOrder') - ]); + computeIdsProcessor.idTemplates.push({ + docTypes: ['error', 'errorNamespace'], + getId: function(doc) { return 'error:' + doc.name; }, + getAliases: function(doc) { return [doc.id]; } + }); +}) - config.append('processing.defaultTagTransforms', [ - require('dgeni-packages/jsdoc/tag-defs/transforms/trim-whitespace') - ]); - config.append('processing.inlineTagDefinitions', [ - require('./inline-tag-defs/type') - ]); +.config(function( + generateIndexPagesProcessor, + generateProtractorTestsProcessor, + generateExamplesProcessor, + debugDeployment, defaultDeployment, + jqueryDeployment, productionDeployment) { - config.set('processing.search.ignoreWordsFile', path.resolve(packagePath, 'ignore.words')); + generateIndexPagesProcessor.deployments = [ + debugDeployment, + defaultDeployment, + jqueryDeployment, + productionDeployment + ]; - config.prepend('rendering.templateFolders', [ - path.resolve(packagePath, 'templates') - ]); + generateProtractorTestsProcessor.deployments = [ + defaultDeployment, + jqueryDeployment + ]; - return config; -}; + generateExamplesProcessor.deployments = [ + debugDeployment, + defaultDeployment, + jqueryDeployment, + productionDeployment + ]; +}); diff --git a/docs/config/inline-tag-defs/type.js b/docs/config/inline-tag-defs/type.js index b0a11b5a63ac..6228a0766fec 100644 --- a/docs/config/inline-tag-defs/type.js +++ b/docs/config/inline-tag-defs/type.js @@ -1,12 +1,17 @@ -var typeClassFilter = require('dgeni-packages/ngdoc/rendering/filters/type-class'); +"use strict"; + var encoder = new require('node-html-encoder').Encoder(); -module.exports = { - name: 'type', - description: 'Replace with markup that displays a nice type', - handlerFactory: function() { - return function(doc, tagName, tagDescription) { - return ''+encoder.htmlEncode(tagDescription) + ''; - }; - } -}; +/** + * @dgService typeInlineTagDef + * @description + * Replace with markup that displays a nice type + */ +module.exports = function typeInlineTagDef(getTypeClass) { + return { + name: 'type', + handler: function(doc, tagName, tagDescription) { + return ''+encoder.htmlEncode(tagDescription) + ''; + } + }; +}; \ No newline at end of file diff --git a/docs/config/processors/debug-dump.js b/docs/config/processors/debug-dump.js deleted file mode 100644 index 5111a0f973c7..000000000000 --- a/docs/config/processors/debug-dump.js +++ /dev/null @@ -1,33 +0,0 @@ -var fs = require('q-io/fs'); -var log = require('winston'); -var util = require("util"); - -module.exports = { - name: 'debug-dump', - runBefore: ['write-files'], - description: 'This processor dumps docs that match a filter to a file', - process: function(docs, config) { - - var filter, outputPath, depth; - - filter = config.get('processing.debug-dump.filter'); - outputPath = config.get('processing.debug-dump.outputPath'); - depth = config.get('processing.debug-dump.depth', 2); - - - if ( filter && outputPath ) { - log.info('Dumping docs:', filter, outputPath); - var filteredDocs = filter(docs); - var dumpedDocs = util.inspect(filteredDocs, depth); - return writeFile(outputPath, dumpedDocs).then(function() { - return docs; - }); - } - } -}; - -function writeFile(file, content) { - return fs.makeTree(fs.directory(file)).then(function() { - return fs.write(file, content, 'wb'); - }); -} diff --git a/docs/config/processors/error-docs.js b/docs/config/processors/error-docs.js index 68a082b77aa3..a86be71df881 100644 --- a/docs/config/processors/error-docs.js +++ b/docs/config/processors/error-docs.js @@ -1,59 +1,52 @@ +"use strict"; + var _ = require('lodash'); -var log = require('winston'); var path = require('canonical-path'); -module.exports = { - name: 'error-docs', - description: 'Compute the various fields for docs in the Error area', - runAfter: ['tags-extracted', 'compute-path'], - runBefore: ['extra-docs-added'], - exports: { - errorNamespaces: ['factory', function() { return {}; }], - minerrInfo: ['factory', function(config) { - var minerrInfoPath = config.get('processing.errors.minerrInfoPath'); - if ( !minerrInfoPath ) { - throw new Error('Error in configuration: Please provide a path to the minerr info file (errors.json) ' + - 'in the `config.processing.errors.minerrInfoPath` property'); - } - return require(minerrInfoPath); - }] - }, - process: function(docs, partialNames, errorNamespaces, minerrInfo) { - - // Create error namespace docs and attach error docs to each - _.forEach(docs, function(doc) { - if ( doc.docType === 'error' ) { - - // Parse out the error info from the id - parts = doc.name.split(':'); - doc.namespace = parts[0]; - doc.name = parts[1]; - - - var namespaceDoc = errorNamespaces[doc.namespace]; - if ( !namespaceDoc ) { - // First time we came across this namespace, so create a new one - namespaceDoc = errorNamespaces[doc.namespace] = { - area: doc.area, - name: doc.namespace, - errors: [], - path: path.dirname(doc.path), - outputPath: path.dirname(doc.outputPath) + '.html', - docType: 'errorNamespace' - }; +/** + * @dgProcessor errorDocsProcessor + * @description + * Process "error" docType docs and generate errorNamespace docs + */ +module.exports = function errorDocsProcessor(errorNamespaceMap, getMinerrInfo) { + return { + $runAfter: ['tags-extracted'], + $runBefore: ['extra-docs-added'], + $process: function(docs) { + + // Create error namespace docs and attach error docs to each + docs.forEach(function(doc) { + var parts, namespaceDoc; + + if ( doc.docType === 'error' ) { + + // Parse out the error info from the id + parts = doc.name.split(':'); + doc.namespace = parts[0]; + doc.name = parts[1]; + + // Get or create the relevant errorNamespace doc + namespaceDoc = errorNamespaceMap.get(doc.namespace); + if ( !namespaceDoc ) { + namespaceDoc = { + area: 'error', + name: doc.namespace, + errors: [], + docType: 'errorNamespace' + }; + errorNamespaceMap.set(doc.namespace, namespaceDoc); + } + + // Link this error doc to its namespace doc + namespaceDoc.errors.push(doc); + doc.namespaceDoc = namespaceDoc; + doc.formattedErrorMessage = getMinerrInfo().errors[doc.namespace][doc.name]; } - - // Add this error to the namespace - namespaceDoc.errors.push(doc); - doc.namespace = namespaceDoc; - - doc.formattedErrorMessage = minerrInfo.errors[doc.namespace.name][doc.name]; - - } - - }); - - - return docs.concat(_.values(errorNamespaces)); - } -}; + }); + + errorNamespaceMap.forEach(function(errorNamespace) { + docs.push(errorNamespace); + }); + } + }; +}; \ No newline at end of file diff --git a/docs/config/processors/git-data.js b/docs/config/processors/git-data.js deleted file mode 100644 index 44d423375768..000000000000 --- a/docs/config/processors/git-data.js +++ /dev/null @@ -1,20 +0,0 @@ -var gruntUtils = require('../../../lib/grunt/utils'); -var versionInfo = require('../../../lib/versions/version-info'); - -module.exports = { - name: 'git-data', - runBefore: ['reading-files'], - description: 'This processor adds information from the local git repository to the extraData injectable', - exports: { - gitData: ['factory', function() { - return { - version: versionInfo.currentVersion, - versions: versionInfo.previousVersions, - info: versionInfo.gitRepoInfo - }; - }] - }, - process: function(extraData, gitData) { - extraData.git = gitData; - } -}; diff --git a/docs/config/processors/index-page.js b/docs/config/processors/index-page.js index 7b5203c23546..9232f7f2a136 100644 --- a/docs/config/processors/index-page.js +++ b/docs/config/processors/index-page.js @@ -1,40 +1,43 @@ +"use strict"; + var _ = require('lodash'); -var log = require('winston'); var path = require('canonical-path'); -module.exports = { - name: 'index-page', - runAfter: ['adding-extra-docs'], - runBefore: ['extra-docs-added'], - description: 'This processor creates docs that will be rendered as the index page for the app', - process: function(docs, config) { - - var deployment = config.deployment; - if ( !deployment || !deployment.environments ) { - throw new Error('No deployment environments found in the config.'); - } +/** + * @dgProcessor generateIndexPagesProcessor + * @description + * This processor creates docs that will be rendered as the index page for the app + */ +module.exports = function generateIndexPagesProcessor() { + return { + deployments: [], + $validate: { + deployments: { presence: true } + }, + $runAfter: ['adding-extra-docs'], + $runBefore: ['extra-docs-added'], + $process: function(docs) { - // Collect up all the areas in the docs - var areas = {}; - _.forEach(docs, function(doc) { - if ( doc.area ) { - areas[doc.area] = doc.area; - } - }); - areas = _.keys(areas); + // Collect up all the areas in the docs + var areas = {}; + docs.forEach(function(doc) { + if ( doc.area ) { + areas[doc.area] = doc.area; + } + }); + areas = _.keys(areas); - _.forEach(deployment.environments, function(environment) { + this.deployments.forEach(function(deployment) { - var indexDoc = _.defaults({ - docType: 'indexPage', - areas: areas - }, environment); + var indexDoc = _.defaults({ + docType: 'indexPage', + areas: areas + }, deployment); - indexDoc.id = 'index' + (environment.name === 'default' ? '' : '-' + environment.name); - // Use .. to put it at the root of the build - indexDoc.outputPath = indexDoc.id + '.html'; + indexDoc.id = 'index' + (deployment.name === 'default' ? '' : '-' + deployment.name); - docs.push(indexDoc); - }); - } -}; + docs.push(indexDoc); + }); + } + }; +}; \ No newline at end of file diff --git a/docs/config/processors/keywords.js b/docs/config/processors/keywords.js index cf029fcc1f9c..4994064aed85 100644 --- a/docs/config/processors/keywords.js +++ b/docs/config/processors/keywords.js @@ -1,51 +1,64 @@ "use strict"; + var _ = require('lodash'); -var log = require('winston'); var fs = require('fs'); var path = require('canonical-path'); -module.exports = { - name: 'keywords', - runAfter: ['docs-processed', 'api-docs'], - runBefore: ['adding-extra-docs'], - description: 'This processor extracts all the keywords from the document', - process: function(docs, config) { - - // Keywords to ignore - var wordsToIgnore = []; - var propertiesToIgnore; - var areasToSearch; - - // Keywords start with "ng:" or one of $, _ or a letter - var KEYWORD_REGEX = /^((ng:|[\$_a-z])[\w\-_]+)/; - - // Load up the keywords to ignore, if specified in the config - if ( config.processing.search && config.processing.search.ignoreWordsFile ) { - - var ignoreWordsPath = path.resolve(config.basePath, config.processing.search.ignoreWordsFile); - wordsToIgnore = fs.readFileSync(ignoreWordsPath, 'utf8').toString().split(/[,\s\n\r]+/gm); +/** + * @dgProcessor generateKeywordsProcessor + * @description + * This processor extracts all the keywords from each document and creates + * a new document that will be rendered as a JavaScript file containing all + * this data. + */ +module.exports = function generateKeywordsProcessor(log, readFilesProcessor) { + return { + ignoreWordsFile: undefined, + areasToSearch: ['api', 'guide', 'misc', 'error', 'tutorial'], + propertiesToIgnore: [], + $validate: { + ignoreWordsFile: { }, + areasToSearch: { presence: true }, + propertiesToIgnore: { } + }, + $runAfter: ['memberDocsProcessor'], + $runBefore: ['rendering-docs'], + $process: function(docs) { + + // Keywords to ignore + var wordsToIgnore = []; + var propertiesToIgnore; + var areasToSearch; + + // Keywords start with "ng:" or one of $, _ or a letter + var KEYWORD_REGEX = /^((ng:|[\$_a-z])[\w\-_]+)/; + + // Load up the keywords to ignore, if specified in the config + if ( this.ignoreWordsFile ) { + + var ignoreWordsPath = path.resolve(readFilesProcessor.basePath, this.ignoreWordsFile); + wordsToIgnore = fs.readFileSync(ignoreWordsPath, 'utf8').toString().split(/[,\s\n\r]+/gm); + + log.debug('Loaded ignore words from "' + ignoreWordsPath + '"'); + log.silly(wordsToIgnore); - log.debug('Loaded ignore words from "' + ignoreWordsPath + '"'); - log.silly(wordsToIgnore); - - } - - areasToSearch = _.indexBy(config.get('processing.search.areasToSearch', ['api', 'guide', 'misc', 'error', 'tutorial'])); + } - propertiesToIgnore = _.indexBy(config.get('processing.search.propertiesToIgnore', [])); - log.debug('Properties to ignore', propertiesToIgnore); + areasToSearch = _.indexBy(this.areasToSearch); + propertiesToIgnore = _.indexBy(this.propertiesToIgnore); + log.debug('Properties to ignore', propertiesToIgnore); - var ignoreWordsMap = _.indexBy(wordsToIgnore); + var ignoreWordsMap = _.indexBy(wordsToIgnore); - // If the title contains a name starting with ng, e.g. "ngController", then add the module name - // without the ng to the title text, e.g. "controller". - function extractTitleWords(title) { - var match = /ng([A-Z]\w*)/.exec(title); - if ( match ) { - title = title + ' ' + match[1].toLowerCase(); + // If the title contains a name starting with ng, e.g. "ngController", then add the module name + // without the ng to the title text, e.g. "controller". + function extractTitleWords(title) { + var match = /ng([A-Z]\w*)/.exec(title); + if ( match ) { + title = title + ' ' + match[1].toLowerCase(); + } + return title; } - return title; - } function extractWords(text, words, keywordMap) { @@ -58,15 +71,15 @@ module.exports = { keywordMap[key] = true; words.push(key); } - } - }); - } + } + }); + } - // We are only interested in docs that live in the right area - docs = _.filter(docs, function(doc) { return areasToSearch[doc.area]; }); + // We are only interested in docs that live in the right area + docs = _.filter(docs, function(doc) { return areasToSearch[doc.area]; }); - _.forEach(docs, function(doc) { + _.forEach(docs, function(doc) { var words = []; var keywordMap = _.clone(ignoreWordsMap); @@ -94,7 +107,8 @@ module.exports = { members: _.sortBy(members).join(' ') }; - }); + }); - } + } + }; }; diff --git a/docs/config/processors/pages-data.js b/docs/config/processors/pages-data.js index 5aead6ec717e..7656db5951bd 100644 --- a/docs/config/processors/pages-data.js +++ b/docs/config/processors/pages-data.js @@ -1,6 +1,7 @@ +"use strict"; + var _ = require('lodash'); var path = require('canonical-path'); -var log = require('winston'); var AREA_NAMES = { api: 'API', @@ -33,189 +34,192 @@ function getNavGroup(pages, area, pageSorter, pageMapper) { } -var navGroupMappers = { - api: function(areaPages, area) { - var navGroups = _(areaPages) - .filter('module') // We are not interested in docs that are not in a module +/** + * @dgProcessor generatePagesDataProcessor + * @description + * This processor will create a new doc that will be rendered as a JavaScript file + * containing meta information about the pages and navigation + */ +module.exports = function generatePagesDataProcessor(log) { - .groupBy('module') - .map(function(modulePages, moduleName) { - log.debug('moduleName: ' + moduleName); - var navItems = []; - var modulePage; + var navGroupMappers = { + api: function(areaPages, area) { + var navGroups = _(areaPages) + .filter('module') // We are not interested in docs that are not in a module - _(modulePages) + .groupBy('module') - .groupBy('docType') + .map(function(modulePages, moduleName) { + log.debug('moduleName: ' + moduleName); + var navItems = []; + var modulePage; - .tap(function(docTypes) { - log.debug(_.keys(docTypes)); - // Extract the module page from the collection - modulePage = docTypes.module[0]; - delete docTypes.module; - }) + _(modulePages) - .tap(function(docTypes) { - if ( docTypes.input ) { - docTypes.directive = docTypes.directive || []; - // Combine input docTypes into directive docTypes - docTypes.directive = docTypes.directive.concat(docTypes.input); - delete docTypes.input; - } - }) + .groupBy('docType') - .forEach(function(sectionPages, sectionName) { + .tap(function(docTypes) { + log.debug(moduleName, _.keys(docTypes)); + // Extract the module page from the collection + modulePage = docTypes.module[0]; + delete docTypes.module; + }) - sectionPages = _.sortBy(sectionPages, 'name'); + .tap(function(docTypes) { + if ( docTypes.input ) { + docTypes.directive = docTypes.directive || []; + // Combine input docTypes into directive docTypes + docTypes.directive = docTypes.directive.concat(docTypes.input); + delete docTypes.input; + } + }) - if ( sectionPages.length > 0 ) { - // Push a navItem for this section - navItems.push({ - name: sectionName, - type: 'section', - href: path.dirname(sectionPages[0].path) - }); + .forEach(function(sectionPages, sectionName) { - // Push the rest of the sectionPages for this section - _.forEach(sectionPages, function(sectionPage) { + sectionPages = _.sortBy(sectionPages, 'name'); + if ( sectionPages.length > 0 ) { + // Push a navItem for this section navItems.push({ - name: sectionPage.name, - href: sectionPage.path, - type: sectionPage.docType + name: sectionName, + type: 'section', + href: path.dirname(sectionPages[0].path) }); - }); - } - }); + // Push the rest of the sectionPages for this section + _.forEach(sectionPages, function(sectionPage) { + + navItems.push({ + name: sectionPage.name, + href: sectionPage.path, + type: sectionPage.docType + }); + + }); + } + }); + return { + name: moduleName, + href: modulePage.path, + type: 'group', + navItems: navItems + }; + }) + .value(); + return navGroups; + }, + tutorial: function(pages, area) { + return [getNavGroup(pages, area, 'step', function(page) { return { - name: moduleName, - href: modulePage.path, - type: 'group', - navItems: navItems + name: page.name, + step: page.step, + href: page.path, + type: 'tutorial' }; - }) - .value(); - return navGroups; - }, - tutorial: function(pages, area) { - return [getNavGroup(pages, area, 'step', function(page) { - return { - name: page.name, - step: page.step, - href: page.path, - type: 'tutorial' - }; - })]; - }, - error: function(pages, area) { - return [getNavGroup(pages, area, 'path', function(page) { - return { - name: page.name, - href: page.path, - type: page.docType === 'errorNamespace' ? 'section' : 'error' - }; - })]; - }, - pages: function(pages, area) { - return [getNavGroup( - pages, - area, - function(page) { - return page.sortOrder || page.path; - }, - function(page) { + })]; + }, + error: function(pages, area) { + return [getNavGroup(pages, area, 'path', function(page) { return { name: page.name, href: page.path, - type: 'page' + type: page.docType === 'errorNamespace' ? 'section' : 'error' }; - } - )]; - } -}; + })]; + }, + pages: function(pages, area) { + return [getNavGroup( + pages, + area, + function(page) { + return page.sortOrder || page.path; + }, + function(page) { + return { + name: page.name, + href: page.path, + type: 'page' + }; + } + )]; + } + }; + + return { + $runAfter: ['paths-computed'], + $runBefore: ['rendering-docs'], + $process: function(docs) { + + _(docs) + .filter(function(doc) { return doc.area === 'api' && doc.docType === 'module'; }) + .forEach(function(doc) { if ( !doc.path ) { + log.warn('Missing path property for ', doc.id); + }}) + .map(function(doc) { return _.pick(doc, ['id', 'module', 'docType', 'area']); }) + .tap(function(docs) { + log.debug(docs); + }); -module.exports = { - name: 'pages-data', - description: 'This plugin will create a new doc that will be rendered as an angularjs module ' + - 'which will contain meta information about the pages and navigation', - runAfter: ['adding-extra-docs', 'component-groups-generate', 'compute-path'], - runBefore: ['extra-docs-added'], - process: function(docs, config) { - - var outputFolder = config.rendering.outputFolder; - - _(docs) - .filter(function(doc) { return doc.area === 'api'; }) - .filter(function(doc) { return doc.docType === 'module'; }) - .forEach(function(doc) { if ( !doc.path ) { - log.warn('Missing path property for ', doc.id); - }}) - .map(function(doc) { return _.pick(doc, ['id', 'module', 'docType', 'area']); }) - .tap(function(docs) { - log.debug(docs); - }); - - - // We are only interested in docs that are in a area and not landing pages - var navPages = _.filter(docs, function(page) { - return page.area && - page.docType != 'componentGroup'; - }); - - // Generate an object collection of pages that is grouped by area e.g. - // - area "api" - // - group "ng" - // - section "directive" - // - ngApp - // - ngBind - // - section "global" - // - angular.element - // - angular.bootstrap - // - section "service" - // - $compile - // - group "ngRoute" - // - section "directive" - // - ngView - // - section "service" - // - $route - // - var areas = {}; - _(navPages) - .groupBy('area') - .forEach(function(pages, areaId) { - var area = { - id: areaId, - name: AREA_NAMES[areaId] - }; - areas[areaId] = area; - var navGroupMapper = navGroupMappers[area.id] || navGroupMappers['pages']; - area.navGroups = navGroupMapper(pages, area); + // We are only interested in docs that are in an area and are not landing pages + var navPages = _.filter(docs, function(page) { + return page.area && page.docType != 'componentGroup'; }); - // Extract a list of basic page information for mapping paths to partials and for client side searching - var pages = _(docs) - .map(function(doc) { - var page = _.pick(doc, [ - 'docType', 'id', 'name', 'area', 'outputPath', 'path', 'searchTerms' - ]); - return page; - }) - .indexBy('path') - .value(); - - - var docData = { - docType: 'pages-data', - id: 'pages-data', - template: 'pages-data.template.js', - outputPath: 'js/pages-data.js', - - areas: areas, - pages: pages - }; - docs.push(docData); + // Generate an object collection of pages that is grouped by area e.g. + // - area "api" + // - group "ng" + // - section "directive" + // - ngApp + // - ngBind + // - section "global" + // - angular.element + // - angular.bootstrap + // - section "service" + // - $compile + // - group "ngRoute" + // - section "directive" + // - ngView + // - section "service" + // - $route + // + var areas = {}; + _(navPages) + .groupBy('area') + .forEach(function(pages, areaId) { + var area = { + id: areaId, + name: AREA_NAMES[areaId] + }; + areas[areaId] = area; + + var navGroupMapper = navGroupMappers[area.id] || navGroupMappers['pages']; + area.navGroups = navGroupMapper(pages, area); + }); + + // Extract a list of basic page information for mapping paths to partials and for client side searching + var pages = _(docs) + .map(function(doc) { + var page = _.pick(doc, [ + 'docType', 'id', 'name', 'area', 'outputPath', 'path', 'searchTerms' + ]); + return page; + }) + .indexBy('path') + .value(); + + var docData = { + docType: 'pages-data', + id: 'pages-data', + template: 'pages-data.template.js', + outputPath: 'js/pages-data.js', + + areas: areas, + pages: pages + }; + + docs.push(docData); + } } }; diff --git a/docs/config/processors/protractor-generate.js b/docs/config/processors/protractor-generate.js deleted file mode 100644 index a925f46a8ce7..000000000000 --- a/docs/config/processors/protractor-generate.js +++ /dev/null @@ -1,50 +0,0 @@ -var _ = require('lodash'); -var path = require('canonical-path'); - -module.exports = { - name: 'protractor-generate', - description: 'Generate a protractor test file from the e2e tests in the examples', - runAfter: ['adding-extra-docs'], - runBefore: ['extra-docs-added'], - process: function(docs, examples, config) { - var protractorFolder = config.get('rendering.protractor.outputFolder', 'ptore2e'); - - _.forEach(examples, function(example) { - - _.forEach(example.files, function(file) { - - // Check if it's a Protractor test. - if (file.type !== 'protractor') { - return; - } - - // Create new files for the tests. - docs.push(createProtractorDoc(example, file, 'jquery')); - docs.push(createProtractorDoc(example, file, 'jqlite')); - }); - }); - - function createProtractorDoc(example, file, env) { - var protractorDoc = { - docType: 'e2e-test', - id: 'protractorTest' + '-' + example.id, - template: 'protractorTests.template.js', - outputPath: path.join(protractorFolder, example.id, env + '_test.js'), - innerTest: file.fileContents, - pathPrefix: '.', // Hold for if we test with full jQuery - exampleId: example.id, - description: example.doc.id, - 'ng-app-included': example['ng-app-included'] - }; - - if (env === 'jquery') { - protractorDoc.examplePath = example.outputFolder + '/index-jquery.html'; - } else { - protractorDoc.examplePath = example.outputFolder + '/index.html'; - } - return protractorDoc; - } - - - } -}; diff --git a/docs/config/processors/versions-data.js b/docs/config/processors/versions-data.js index c9494c645c21..636cf78e35c4 100644 --- a/docs/config/processors/versions-data.js +++ b/docs/config/processors/versions-data.js @@ -1,38 +1,34 @@ -var _ = require('lodash'); - -module.exports = { - name: 'versions-data', - description: 'This plugin will create a new doc that will be rendered as an angularjs module ' + - 'which will contain meta information about the versions of angular', - runAfter: ['adding-extra-docs', 'pages-data'], - runBefore: ['extra-docs-added'], - process: function(docs, gitData) { +"use strict"; - var version = gitData.version; - var versions = gitData.versions; - - if ( !version ) { - throw new Error('Invalid configuration. Please provide a valid `source.currentVersion` property'); - } - if ( !versions ) { - throw new Error('Invalid configuration. Please provide a valid `source.previousVersions` property'); - } +var _ = require('lodash'); - var versionDoc = { - docType: 'versions-data', - id: 'versions-data', - template: 'versions-data.template.js', - outputPath: 'js/versions-data.js', - }; +/** + * @dgProcessor generateVersionDocProcessor + * @description + * This processor will create a new doc that will be rendered as a JavaScript file + * containing meta information about the current versions of AngularJS + */ +module.exports = function generateVersionDocProcessor(gitData) { + return { + $runAfter: ['generatePagesDataProcessor'], + $runBefore: ['rendering-docs'], + $process: function(docs) { - versionDoc.currentVersion = version; + var versionDoc = { + docType: 'versions-data', + id: 'versions-data', + template: 'versions-data.template.js', + outputPath: 'js/versions-data.js', + currentVersion: gitData.version + }; - versionDoc.versions = _(versions) - .filter(function(version) { return version.major > 0; }) - .push(version) - .reverse() - .value(); + versionDoc.versions = _(gitData.versions) + .filter(function(version) { return version.major > 0; }) + .push(gitData.version) + .reverse() + .value(); - docs.push(versionDoc); - } -}; + docs.push(versionDoc); + } + }; +}; \ No newline at end of file diff --git a/docs/config/services/deployments/debug.js b/docs/config/services/deployments/debug.js new file mode 100644 index 000000000000..f6be3dafe83b --- /dev/null +++ b/docs/config/services/deployments/debug.js @@ -0,0 +1,39 @@ +"use strict"; + +module.exports = function debugDeployment(getVersion) { + return { + name: 'debug', + examples: { + commonFiles: { + scripts: [ '../../../angular.js' ] + }, + dependencyPath: '../../../' + }, + scripts: [ + '../angular.js', + '../angular-resource.js', + '../angular-route.js', + '../angular-cookies.js', + '../angular-sanitize.js', + '../angular-touch.js', + '../angular-animate.js', + 'components/marked-' + getVersion('marked', 'node_modules', 'package.json') + '/lib/marked.js', + 'js/angular-bootstrap/bootstrap.js', + 'js/angular-bootstrap/bootstrap-prettify.js', + 'js/angular-bootstrap/dropdown-toggle.js', + 'components/lunr.js-' + getVersion('lunr.js') + '/lunr.js', + 'components/google-code-prettify-' + getVersion('google-code-prettify') + '/src/prettify.js', + 'components/google-code-prettify-' + getVersion('google-code-prettify') + '/src/lang-css.js', + 'js/versions-data.js', + 'js/pages-data.js', + 'js/docs.js' + ], + stylesheets: [ + 'components/bootstrap-' + getVersion('bootstrap') + '/css/bootstrap.css', + 'components/open-sans-fontface-' + getVersion('open-sans-fontface') + '/open-sans.css', + 'css/prettify-theme.css', + 'css/docs.css', + 'css/animations.css' + ] + }; +}; \ No newline at end of file diff --git a/docs/config/services/deployments/default.js b/docs/config/services/deployments/default.js new file mode 100644 index 000000000000..c12ff4f3b7b0 --- /dev/null +++ b/docs/config/services/deployments/default.js @@ -0,0 +1,39 @@ +"use strict"; + +module.exports = function defaultDeployment(getVersion) { + return { + name: 'default', + examples: { + commonFiles: { + scripts: [ '../../../angular.min.js' ] + }, + dependencyPath: '../../../' + }, + scripts: [ + '../angular.min.js', + '../angular-resource.min.js', + '../angular-route.min.js', + '../angular-cookies.min.js', + '../angular-sanitize.min.js', + '../angular-touch.min.js', + '../angular-animate.min.js', + 'components/marked-' + getVersion('marked', 'node_modules', 'package.json') + '/lib/marked.js', + 'js/angular-bootstrap/bootstrap.js', + 'js/angular-bootstrap/bootstrap-prettify.js', + 'js/angular-bootstrap/dropdown-toggle.js', + 'components/lunr.js-' + getVersion('lunr.js') + '/lunr.min.js', + 'components/google-code-prettify-' + getVersion('google-code-prettify') + '/src/prettify.js', + 'components/google-code-prettify-' + getVersion('google-code-prettify') + '/src/lang-css.js', + 'js/versions-data.js', + 'js/pages-data.js', + 'js/docs.js' + ], + stylesheets: [ + 'components/bootstrap-' + getVersion('bootstrap') + '/css/bootstrap.min.css', + 'components/open-sans-fontface-' + getVersion('open-sans-fontface') + '/open-sans.css', + 'css/prettify-theme.css', + 'css/docs.css', + 'css/animations.css' + ] + }; +}; \ No newline at end of file diff --git a/docs/config/services/deployments/jquery.js b/docs/config/services/deployments/jquery.js new file mode 100644 index 000000000000..55340b1e7f80 --- /dev/null +++ b/docs/config/services/deployments/jquery.js @@ -0,0 +1,43 @@ +"use strict"; + +module.exports = function jqueryDeployment(getVersion) { + return { + name: 'jquery', + examples: { + commonFiles: { + scripts: [ + '../../components/jquery-' + getVersion('jquery') + '/jquery.js', + '../../../angular.js' + ] + }, + dependencyPath: '../../../' + }, + scripts: [ + 'components/jquery-' + getVersion('jquery') + '/jquery.js', + '../angular.min.js', + '../angular-resource.min.js', + '../angular-route.min.js', + '../angular-cookies.min.js', + '../angular-sanitize.min.js', + '../angular-touch.min.js', + '../angular-animate.min.js', + 'components/marked-' + getVersion('marked', 'node_modules', 'package.json') + '/lib/marked.js', + 'js/angular-bootstrap/bootstrap.js', + 'js/angular-bootstrap/bootstrap-prettify.js', + 'js/angular-bootstrap/dropdown-toggle.js', + 'components/lunr.js-' + getVersion('lunr.js') + '/lunr.min.js', + 'components/google-code-prettify-' + getVersion('google-code-prettify') + '/src/prettify.js', + 'components/google-code-prettify-' + getVersion('google-code-prettify') + '/src/lang-css.js', + 'js/versions-data.js', + 'js/pages-data.js', + 'js/docs.js' + ], + stylesheets: [ + 'components/bootstrap-' + getVersion('bootstrap') + '/css/bootstrap.min.css', + 'components/open-sans-fontface-' + getVersion('open-sans-fontface') + '/open-sans.css', + 'css/prettify-theme.css', + 'css/docs.css', + 'css/animations.css' + ] + }; +}; \ No newline at end of file diff --git a/docs/config/services/deployments/production.js b/docs/config/services/deployments/production.js new file mode 100644 index 000000000000..13d18a160a2a --- /dev/null +++ b/docs/config/services/deployments/production.js @@ -0,0 +1,42 @@ +"use strict"; + +var versionInfo = require('../../../../lib/versions/version-info'); +var cdnUrl = "//ajax.googleapis.com/ajax/libs/angularjs/" + versionInfo.cdnVersion; + +module.exports = function productionDeployment(getVersion) { + return { + name: 'production', + examples: { + commonFiles: { + scripts: [ cdnUrl + '/angular.min.js' ] + }, + dependencyPath: cdnUrl + '/' + }, + scripts: [ + cdnUrl + '/angular.min.js', + cdnUrl + '/angular-resource.min.js', + cdnUrl + '/angular-route.min.js', + cdnUrl + '/angular-cookies.min.js', + cdnUrl + '/angular-sanitize.min.js', + cdnUrl + '/angular-touch.min.js', + cdnUrl + '/angular-animate.min.js', + 'components/marked-' + getVersion('marked', 'node_modules', 'package.json') + '/lib/marked.js', + 'js/angular-bootstrap/bootstrap.js', + 'js/angular-bootstrap/bootstrap-prettify.js', + 'js/angular-bootstrap/dropdown-toggle.js', + 'components/lunr.js-' + getVersion('lunr.js') + '/lunr.min.js', + 'components/google-code-prettify-' + getVersion('google-code-prettify') + '/src/prettify.js', + 'components/google-code-prettify-' + getVersion('google-code-prettify') + '/src/lang-css.js', + 'js/versions-data.js', + 'js/pages-data.js', + 'js/docs.js' + ], + stylesheets: [ + 'components/bootstrap-' + getVersion('bootstrap') + '/css/bootstrap.min.css', + 'components/open-sans-fontface-' + getVersion('open-sans-fontface') + '/open-sans.css', + 'css/prettify-theme.css', + 'css/docs.css', + 'css/animations.css' + ] + }; +}; \ No newline at end of file diff --git a/docs/config/services/errorNamespaceMap.js b/docs/config/services/errorNamespaceMap.js new file mode 100644 index 000000000000..632a625c3ac5 --- /dev/null +++ b/docs/config/services/errorNamespaceMap.js @@ -0,0 +1,10 @@ +"use strict"; +var StringMap = require('stringmap'); + +/** + * @dgService errorNamespaceMap + * A map of error namespaces by name. + */ +module.exports = function errorNamespaceMap() { + return new StringMap(); +}; \ No newline at end of file diff --git a/docs/config/services/getMinerrInfo.js b/docs/config/services/getMinerrInfo.js new file mode 100644 index 000000000000..9538bdc0bf5e --- /dev/null +++ b/docs/config/services/getMinerrInfo.js @@ -0,0 +1,15 @@ +"use strict"; + +var path = require('canonical-path'); + +/** + * @dgService minErrInfo + * @description + * Load the error information that was generated during the AngularJS build. + */ +module.exports = function getMinerrInfo(readFilesProcessor) { + return function() { + var minerrInfoPath = path.resolve(readFilesProcessor.basePath, 'build/errors.json'); + return require(minerrInfoPath); + }; +}; diff --git a/docs/config/services/getVersion.js b/docs/config/services/getVersion.js new file mode 100644 index 000000000000..e719196c11a1 --- /dev/null +++ b/docs/config/services/getVersion.js @@ -0,0 +1,17 @@ +"use strict"; +var path = require('canonical-path'); + +/** + * dgService getVersion + * @description + * Find the current version of the bower component (or npm module) + */ +module.exports = function getVersion(readFilesProcessor) { + var basePath = readFilesProcessor.basePath; + + return function(component, sourceFolder, packageFile) { + sourceFolder = path.resolve(basePath, sourceFolder || 'docs/bower_components'); + packageFile = packageFile || 'bower.json'; + return require(path.join(sourceFolder,component,packageFile)).version; + }; +}; \ No newline at end of file diff --git a/docs/config/services/gitData.js b/docs/config/services/gitData.js new file mode 100644 index 000000000000..09f5e34bd215 --- /dev/null +++ b/docs/config/services/gitData.js @@ -0,0 +1,17 @@ +"use strict"; + +var gruntUtils = require('../../../lib/grunt/utils'); +var versionInfo = require('../../../lib/versions/version-info'); + +/** + * @dgService gitData + * @description + * Information from the local git repository + */ +module.exports = function gitData() { + return { + version: versionInfo.currentVersion, + versions: versionInfo.previousVersions, + info: versionInfo.gitRepoInfo + }; +}; diff --git a/docs/config/templates/protractorTests.template.js b/docs/config/templates/protractorTests.template.js deleted file mode 100644 index d26c2703c9ef..000000000000 --- a/docs/config/templates/protractorTests.template.js +++ /dev/null @@ -1,10 +0,0 @@ -describe("{$ doc.description $}", function() { - var rootEl; - beforeEach(function() { - rootEl = browser.rootEl;{% if doc['ng-app-included'] %} - browser.rootEl = '[ng-app]';{% endif %} - browser.get("{$ doc.pathPrefix $}/{$ doc.examplePath $}"); - }); - {% if doc['ng-app-included'] %}afterEach(function() { browser.rootEl = rootEl; });{% endif %} -{$ doc.innerTest $} -}); diff --git a/docs/config/templates/runnableExample.template.html b/docs/config/templates/runnableExample.template.html index d035c08d65e0..951744fd91d6 100644 --- a/docs/config/templates/runnableExample.template.html +++ b/docs/config/templates/runnableExample.template.html @@ -2,15 +2,16 @@ is HTML and wrap each line in a

- thus breaking the HTML #}

- +   Edit in Plunker +
- {% for fileName, file in doc.example.files %} + {% for fileName, file in doc.example.files %}
{% code -%} @@ -19,7 +20,7 @@
{% endfor %} - +
diff --git a/docs/docs.config.js b/docs/docs.config.js deleted file mode 100644 index 5188cc5a9e3d..000000000000 --- a/docs/docs.config.js +++ /dev/null @@ -1,188 +0,0 @@ -"use strict"; - -var path = require('canonical-path'); -var versionInfo = require('../lib/versions/version-info'); -var basePath = __dirname; - -var basePackage = require('./config'); - -module.exports = function(config) { - - var cdnUrl = "//ajax.googleapis.com/ajax/libs/angularjs/" + versionInfo.cdnVersion; - - var getVersion = function(component, sourceFolder, packageFile) { - sourceFolder = sourceFolder || './bower_components'; - packageFile = packageFile || 'bower.json'; - - return require(path.resolve(sourceFolder,component,packageFile)).version; - }; - - - config = basePackage(config); - - config.set('source.projectPath', path.resolve(basePath, '..')); - - config.set('source.files', [ - { pattern: 'src/**/*.js', basePath: path.resolve(basePath,'..') }, - { pattern: '**/*.ngdoc', basePath: path.resolve(basePath, 'content') } - ]); - - config.set('processing.stopOnError', true); - - config.set('processing.errors.minerrInfoPath', path.resolve(basePath, '../build/errors.json')); - - config.set('rendering.outputFolder', '../build/docs'); - config.set('rendering.contentsFolder', 'partials'); - - config.set('logging.level', 'info'); - - config.merge('deployment', { - environments: [{ - name: 'debug', - examples: { - commonFiles: { - scripts: [ '../../../angular.js' ] - }, - dependencyPath: '../../../' - }, - scripts: [ - '../angular.js', - '../angular-resource.js', - '../angular-route.js', - '../angular-cookies.js', - '../angular-sanitize.js', - '../angular-touch.js', - '../angular-animate.js', - 'components/marked-' + getVersion('marked', '../node_modules', 'package.json') + '/lib/marked.js', - 'js/angular-bootstrap/bootstrap.js', - 'js/angular-bootstrap/bootstrap-prettify.js', - 'js/angular-bootstrap/dropdown-toggle.js', - 'components/lunr.js-' + getVersion('lunr.js') + '/lunr.js', - 'components/google-code-prettify-' + getVersion('google-code-prettify') + '/src/prettify.js', - 'components/google-code-prettify-' + getVersion('google-code-prettify') + '/src/lang-css.js', - 'js/versions-data.js', - 'js/pages-data.js', - 'js/docs.js' - ], - stylesheets: [ - 'components/bootstrap-' + getVersion('bootstrap') + '/css/bootstrap.css', - 'components/open-sans-fontface-' + getVersion('open-sans-fontface') + '/open-sans.css', - 'css/prettify-theme.css', - 'css/docs.css', - 'css/animations.css' - ] - }, - { - name: 'default', - examples: { - commonFiles: { - scripts: [ '../../../angular.min.js' ] - }, - dependencyPath: '../../../' - }, - scripts: [ - '../angular.min.js', - '../angular-resource.min.js', - '../angular-route.min.js', - '../angular-cookies.min.js', - '../angular-sanitize.min.js', - '../angular-touch.min.js', - '../angular-animate.min.js', - 'components/marked-' + getVersion('marked', '../node_modules', 'package.json') + '/lib/marked.js', - 'js/angular-bootstrap/bootstrap.js', - 'js/angular-bootstrap/bootstrap-prettify.js', - 'js/angular-bootstrap/dropdown-toggle.js', - 'components/lunr.js-' + getVersion('lunr.js') + '/lunr.min.js', - 'components/google-code-prettify-' + getVersion('google-code-prettify') + '/src/prettify.js', - 'components/google-code-prettify-' + getVersion('google-code-prettify') + '/src/lang-css.js', - 'js/versions-data.js', - 'js/pages-data.js', - 'js/docs.js' - ], - stylesheets: [ - 'components/bootstrap-' + getVersion('bootstrap') + '/css/bootstrap.min.css', - 'components/open-sans-fontface-' + getVersion('open-sans-fontface') + '/open-sans.css', - 'css/prettify-theme.css', - 'css/docs.css', - 'css/animations.css' - ] - }, - { - name: 'jquery', - examples: { - commonFiles: { - scripts: [ - '../../components/jquery-' + getVersion('jquery') + '/jquery.js', - '../../../angular.js' - ] - }, - dependencyPath: '../../../' - }, - scripts: [ - 'components/jquery-' + getVersion('jquery') + '/jquery.js', - '../angular.min.js', - '../angular-resource.min.js', - '../angular-route.min.js', - '../angular-cookies.min.js', - '../angular-sanitize.min.js', - '../angular-touch.min.js', - '../angular-animate.min.js', - 'components/marked-' + getVersion('marked', '../node_modules', 'package.json') + '/lib/marked.js', - 'js/angular-bootstrap/bootstrap.js', - 'js/angular-bootstrap/bootstrap-prettify.js', - 'js/angular-bootstrap/dropdown-toggle.js', - 'components/lunr.js-' + getVersion('lunr.js') + '/lunr.min.js', - 'components/google-code-prettify-' + getVersion('google-code-prettify') + '/src/prettify.js', - 'components/google-code-prettify-' + getVersion('google-code-prettify') + '/src/lang-css.js', - 'js/versions-data.js', - 'js/pages-data.js', - 'js/docs.js' - ], - stylesheets: [ - 'components/bootstrap-' + getVersion('bootstrap') + '/css/bootstrap.min.css', - 'components/open-sans-fontface-' + getVersion('open-sans-fontface') + '/open-sans.css', - 'css/prettify-theme.css', - 'css/docs.css', - 'css/animations.css' - ] - }, - { - name: 'production', - examples: { - commonFiles: { - scripts: [ cdnUrl + '/angular.min.js' ] - }, - dependencyPath: cdnUrl + '/' - }, - scripts: [ - cdnUrl + '/angular.min.js', - cdnUrl + '/angular-resource.min.js', - cdnUrl + '/angular-route.min.js', - cdnUrl + '/angular-cookies.min.js', - cdnUrl + '/angular-sanitize.min.js', - cdnUrl + '/angular-touch.min.js', - cdnUrl + '/angular-animate.min.js', - 'components/marked-' + getVersion('marked', '../node_modules', 'package.json') + '/lib/marked.js', - 'js/angular-bootstrap/bootstrap.js', - 'js/angular-bootstrap/bootstrap-prettify.js', - 'js/angular-bootstrap/dropdown-toggle.js', - 'components/lunr.js-' + getVersion('lunr.js') + '/lunr.min.js', - 'components/google-code-prettify-' + getVersion('google-code-prettify') + '/src/prettify.js', - 'components/google-code-prettify-' + getVersion('google-code-prettify') + '/src/lang-css.js', - 'js/versions-data.js', - 'js/pages-data.js', - 'js/docs.js' - ], - stylesheets: [ - 'components/bootstrap-' + getVersion('bootstrap') + '/css/bootstrap.min.css', - 'components/open-sans-fontface-' + getVersion('open-sans-fontface') + '/open-sans.css', - 'css/prettify-theme.css', - 'css/docs.css', - 'css/animations.css' - ] - } - ] - }); - - return config; -}; diff --git a/docs/gulpfile.js b/docs/gulpfile.js index 3ec16b21e4c2..a0e55b4543ee 100644 --- a/docs/gulpfile.js +++ b/docs/gulpfile.js @@ -5,7 +5,7 @@ var log = require('gulp-util').log; var concat = require('gulp-concat'); var jshint = require('gulp-jshint'); var bower = require('bower'); -var dgeni = require('dgeni'); +var Dgeni = require('dgeni'); var merge = require('event-stream').merge; var path = require('canonical-path'); @@ -59,11 +59,10 @@ gulp.task('assets', ['bower'], function() { gulp.task('doc-gen', ['bower'], function() { - var generateDocs = dgeni.generator('docs.config.js'); - return generateDocs() - .catch(function(error) { - process.exit(1); - }); + var dgeni = new Dgeni([require('./config')]); + return dgeni.generate().catch(function(error) { + process.exit(1); + }); }); // JSHint the example and protractor test files diff --git a/npm-shrinkwrap.json b/npm-shrinkwrap.json index afa0d8fe1b53..71da46a26a14 100644 --- a/npm-shrinkwrap.json +++ b/npm-shrinkwrap.json @@ -1106,10 +1106,18 @@ "version": "0.0.2" }, "dgeni": { - "version": "0.3.0", + "version": "0.4.0-rc.2", "dependencies": { - "rimraf": { - "version": "2.2.8" + "dependency-graph": { + "version": "0.1.0", + "dependencies": { + "underscore": { + "version": "1.4.4" + } + } + }, + "di": { + "version": "0.0.1" }, "optimist": { "version": "0.6.1", @@ -1125,75 +1133,128 @@ "lodash": { "version": "2.4.1" }, - "dependency-graph": { - "version": "0.1.0", - "dependencies": { - "underscore": { - "version": "1.4.4" - } - } - }, "q": { "version": "0.9.7" }, - "di": { - "version": "0.0.1" + "validate.js": { + "version": "0.2.0" } } }, "dgeni-packages": { - "version": "0.9.8", + "version": "0.10.0-rc.3", "dependencies": { - "lodash": { - "version": "2.4.1" + "catharsis": { + "version": "0.7.1" }, - "graceful-fs": { - "version": "2.0.3" + "change-case": { + "version": "2.1.5", + "dependencies": { + "camel-case": { + "version": "1.0.2" + }, + "constant-case": { + "version": "1.0.0" + }, + "dot-case": { + "version": "1.0.1" + }, + "is-lower-case": { + "version": "1.0.0" + }, + "is-upper-case": { + "version": "1.0.1" + }, + "lower-case": { + "version": "1.0.2" + }, + "param-case": { + "version": "1.0.1" + }, + "pascal-case": { + "version": "1.0.0" + }, + "path-case": { + "version": "1.0.1" + }, + "sentence-case": { + "version": "1.0.3" + }, + "snake-case": { + "version": "1.0.1" + }, + "swap-case": { + "version": "1.0.2" + }, + "title-case": { + "version": "1.0.1" + }, + "upper-case": { + "version": "1.0.3" + }, + "upper-case-first": { + "version": "1.0.1" + } + } }, - "glob": { - "version": "3.2.11", + "dgeni": { + "version": "0.4.0-rc.2", "dependencies": { - "inherits": { - "version": "2.0.1" + "dependency-graph": { + "version": "0.1.0", + "dependencies": { + "underscore": { + "version": "1.4.4" + } + } }, - "minimatch": { - "version": "0.3.0", + "di": { + "version": "0.0.1" + }, + "optimist": { + "version": "0.6.1", "dependencies": { - "lru-cache": { - "version": "2.5.0" + "wordwrap": { + "version": "0.0.2" }, - "sigmund": { - "version": "1.0.0" + "minimist": { + "version": "0.0.10" } } + }, + "q": { + "version": "0.9.7" + }, + "validate.js": { + "version": "0.2.0" } } }, - "q-io": { - "version": "1.10.9", + "esprima": { + "version": "1.2.2" + }, + "glob": { + "version": "3.2.11", "dependencies": { - "q": { - "version": "0.9.7" - }, - "qs": { - "version": "0.1.0" - }, - "url2": { - "version": "0.0.0" - }, - "mime": { - "version": "1.2.11" - }, - "mimeparse": { - "version": "0.1.4" + "inherits": { + "version": "2.0.1" + } + } + }, + "lodash": { + "version": "2.4.1" + }, + "marked": { + "version": "0.2.10" + }, + "minimatch": { + "version": "0.3.0", + "dependencies": { + "lru-cache": { + "version": "2.5.0" }, - "collections": { - "version": "0.2.2", - "dependencies": { - "weak-map": { - "version": "1.0.0" - } - } + "sigmund": { + "version": "1.0.0" } } }, @@ -1231,64 +1292,33 @@ } } }, - "catharsis": { - "version": "0.7.1" - }, - "esprima": { - "version": "1.2.2" - }, - "change-case": { - "version": "2.1.5", + "q-io": { + "version": "1.10.9", "dependencies": { - "camel-case": { - "version": "1.0.2" - }, - "constant-case": { - "version": "1.0.0" - }, - "dot-case": { - "version": "1.0.1" - }, - "is-lower-case": { - "version": "1.0.0" - }, - "is-upper-case": { - "version": "1.0.1" - }, - "lower-case": { - "version": "1.0.2" - }, - "param-case": { - "version": "1.0.1" - }, - "pascal-case": { - "version": "1.0.0" - }, - "path-case": { - "version": "1.0.1" - }, - "sentence-case": { - "version": "1.0.3" + "q": { + "version": "0.9.7" }, - "snake-case": { - "version": "1.0.1" + "qs": { + "version": "0.1.0" }, - "swap-case": { - "version": "1.0.2" + "url2": { + "version": "0.0.0" }, - "title-case": { - "version": "1.0.1" + "mime": { + "version": "1.2.11" }, - "upper-case": { - "version": "1.0.3" + "mimeparse": { + "version": "0.1.4" }, - "upper-case-first": { - "version": "1.0.1" + "collections": { + "version": "0.2.2", + "dependencies": { + "weak-map": { + "version": "1.0.0" + } + } } } - }, - "marked": { - "version": "0.2.10" } } }, @@ -1942,147 +1972,6 @@ "deprecated": { "version": "0.0.1" }, - "gulp-util": { - "version": "3.0.1", - "dependencies": { - "dateformat": { - "version": "1.0.8-1.2.3" - }, - "lodash": { - "version": "2.4.1" - }, - "lodash._reinterpolate": { - "version": "2.4.1" - }, - "lodash.template": { - "version": "2.4.1", - "dependencies": { - "lodash.defaults": { - "version": "2.4.1", - "dependencies": { - "lodash._objecttypes": { - "version": "2.4.1" - } - } - }, - "lodash.escape": { - "version": "2.4.1", - "dependencies": { - "lodash._escapehtmlchar": { - "version": "2.4.1", - "dependencies": { - "lodash._htmlescapes": { - "version": "2.4.1" - } - } - }, - "lodash._reunescapedhtml": { - "version": "2.4.1", - "dependencies": { - "lodash._htmlescapes": { - "version": "2.4.1" - } - } - } - } - }, - "lodash._escapestringchar": { - "version": "2.4.1" - }, - "lodash.keys": { - "version": "2.4.1", - "dependencies": { - "lodash._isnative": { - "version": "2.4.1" - }, - "lodash.isobject": { - "version": "2.4.1", - "dependencies": { - "lodash._objecttypes": { - "version": "2.4.1" - } - } - }, - "lodash._shimkeys": { - "version": "2.4.1", - "dependencies": { - "lodash._objecttypes": { - "version": "2.4.1" - } - } - } - } - }, - "lodash.templatesettings": { - "version": "2.4.1" - }, - "lodash.values": { - "version": "2.4.1" - } - } - }, - "multipipe": { - "version": "0.1.1", - "dependencies": { - "duplexer2": { - "version": "0.0.2", - "dependencies": { - "readable-stream": { - "version": "1.1.13", - "dependencies": { - "core-util-is": { - "version": "1.0.1" - }, - "isarray": { - "version": "0.0.1" - }, - "string_decoder": { - "version": "0.10.31" - }, - "inherits": { - "version": "2.0.1" - } - } - } - } - } - } - }, - "through2": { - "version": "0.6.1", - "dependencies": { - "readable-stream": { - "version": "1.0.31", - "dependencies": { - "core-util-is": { - "version": "1.0.1" - }, - "isarray": { - "version": "0.0.1" - }, - "string_decoder": { - "version": "0.10.31" - }, - "inherits": { - "version": "2.0.1" - } - } - }, - "xtend": { - "version": "4.0.0" - } - } - }, - "vinyl": { - "version": "0.4.3", - "dependencies": { - "clone-stats": { - "version": "0.0.1" - } - } - } - } - }, "interpret": { "version": "0.3.6" }, diff --git a/package.json b/package.json index ab736f555fb2..869022290f1f 100644 --- a/package.json +++ b/package.json @@ -11,8 +11,8 @@ "bower": "~1.3.9", "browserstacktunnel-wrapper": "~1.1.1", "canonical-path": "0.0.2", - "dgeni": "^0.3.0", - "dgeni-packages": "^0.9.8", + "dgeni": "^0.4.0", + "dgeni-packages": "^0.10.0", "es6-shim": "^0.14.0", "event-stream": "~3.1.0", "grunt": "~0.4.2", diff --git a/scripts/travis/build.sh b/scripts/travis/build.sh index bb29c5cd5a7d..41739650ae86 100755 --- a/scripts/travis/build.sh +++ b/scripts/travis/build.sh @@ -9,12 +9,11 @@ if [ $JOB = "unit" ]; then grunt test:promises-aplus grunt test:unit --browsers SL_Chrome,SL_Safari,SL_Firefox,SL_IE_8,SL_IE_9,SL_IE_10,SL_IE_11 --reporters dots grunt tests:docs --browsers SL_Chrome,SL_Safari,SL_Firefox,SL_IE_8,SL_IE_9,SL_IE_10,SL_IE_11 --reporters dots + grunt test:travis-protractor --specs "docs/app/e2e/docsAppE2E.js" elif [ $JOB = "e2e" ]; then - export TARGET_SPECS="build/docs/ptore2e/**/*jqlite_test.js" + export TARGET_SPECS="build/docs/ptore2e/**/default_test.js" if [ $TEST_TARGET = "jquery" ]; then - TARGET_SPECS="build/docs/ptore2e/**/*jquery_test.js" - elif [ $TEST_TARGET = "doce2e" ]; then - TARGET_SPECS="docs/app/e2e/docsAppE2E.js" + TARGET_SPECS="build/docs/ptore2e/**/jquery_test.js" fi grunt test:travis-protractor --specs "$TARGET_SPECS" else From 9b9a30c7aef24012df0da6e6f8ca37b07dff0daa Mon Sep 17 00:00:00 2001 From: Peter Bacon Darwin Date: Mon, 15 Sep 2014 20:35:20 +0100 Subject: [PATCH 2/8] test(docs): improve docs e2e tests --- docs/app/e2e/.jshintrc | 42 +++++++++++++++++++ docs/app/e2e/api-pages.scenario.js | 41 ++++++++++++++++++ .../e2e/{docsAppE2E.js => app.scenario.js} | 30 +++---------- docs/protractor-conf.js | 13 ++++++ protractor-conf.js | 2 +- protractor-jenkins-conf.js | 2 +- scripts/travis/build.sh | 2 +- 7 files changed, 105 insertions(+), 27 deletions(-) create mode 100644 docs/app/e2e/.jshintrc create mode 100644 docs/app/e2e/api-pages.scenario.js rename docs/app/e2e/{docsAppE2E.js => app.scenario.js} (67%) create mode 100644 docs/protractor-conf.js diff --git a/docs/app/e2e/.jshintrc b/docs/app/e2e/.jshintrc new file mode 100644 index 000000000000..6e3ae3068ad3 --- /dev/null +++ b/docs/app/e2e/.jshintrc @@ -0,0 +1,42 @@ +{ + "extends": "../../../.jshintrc-base", + + "globals": { + + /* jasmine / karma */ + "it": false, + "iit": false, + "describe": false, + "ddescribe": false, + "beforeEach": false, + "afterEach": false, + "expect": false, + "jasmine": false, + "spyOn": false, + "waits": false, + "waitsFor": false, + "runs": false, + "dump": false, + + /* e2e */ + "browser": false, + "element": false, + "by": false, + + /* testabilityPatch / matchers */ + "inject": false, + "module": false, + "dealoc": false, + "_jQuery": false, + "_jqLiteMode": false, + "sortedHtml": false, + "childrenTagsOf": false, + "assertHidden": false, + "assertVisible": false, + "provideLog": false, + "spyOnlyCallsWithArgs": false, + "createMockStyleSheet": false, + "browserTrigger": false, + "jqLiteCacheSize": false + } +} \ No newline at end of file diff --git a/docs/app/e2e/api-pages.scenario.js b/docs/app/e2e/api-pages.scenario.js new file mode 100644 index 000000000000..76ee7a1165f3 --- /dev/null +++ b/docs/app/e2e/api-pages.scenario.js @@ -0,0 +1,41 @@ +'use strict'; + +describe("doc.angularjs.org", function() { + + describe("API pages", function() { + + it("should display links to code on GitHub", function() { + browser.get('index-debug.html#!/api/ng/service/$http'); + expect(element(by.css('.improve-docs')).getAttribute('href')).toMatch(/https?:\/\/github\.com\/angular\/angular\.js\/edit\/.+\/src\/ng\/http\.js/); + + browser.get('index-debug.html#!/api/ng/service/$http'); + expect(element(by.css('.view-source')).getAttribute('href')).toMatch(/https?:\/\/github\.com\/angular\/angular\.js\/tree\/.+\/src\/ng\/http\.js#L\d+/); + }); + + it('should change the page content when clicking a link to a service', function () { + browser.get(''); + + var ngBindLink = element(by.css('.definition-table td a[href="api/ng/directive/ngClick"]')); + ngBindLink.click(); + + var pageBody = element(by.css('h1')); + expect(pageBody.getText()).toEqual('ngClick'); + }); + + + it('should show the functioning input directive example', function () { + browser.get('index-debug.html#!/api/ng/directive/input'); + + // Ensure that the page is loaded before trying to switch frames. + browser.waitForAngular(); + + browser.switchTo().frame('example-input-directive'); + + var nameInput = element(by.model('user.name')); + nameInput.sendKeys('!!!'); + + var code = element.all(by.css('tt')).first(); + expect(code.getText()).toContain('guest!!!'); + }); + }); +}); \ No newline at end of file diff --git a/docs/app/e2e/docsAppE2E.js b/docs/app/e2e/app.scenario.js similarity index 67% rename from docs/app/e2e/docsAppE2E.js rename to docs/app/e2e/app.scenario.js index d8733f7c0a25..ef063980d558 100644 --- a/docs/app/e2e/docsAppE2E.js +++ b/docs/app/e2e/app.scenario.js @@ -26,21 +26,6 @@ describe('docs.angularjs.org', function () { }); - it('should show the functioning input directive example', function () { - browser.get('index-debug.html#!/api/ng/directive/input'); - - // Ensure that the page is loaded before trying to switch frames. - browser.waitForAngular(); - - browser.switchTo().frame('example-input-directive'); - - var nameInput = element(by.model('user.name')); - nameInput.sendKeys('!!!'); - - var code = element.all(by.css('tt')).first(); - expect(code.getText()).toContain('guest!!!'); - }); - it('should be resilient to trailing slashes', function() { browser.get('index-debug.html#!/api/ng/function/angular.noop/'); @@ -67,6 +52,12 @@ describe('docs.angularjs.org', function () { browser.get('index-debug.html#!error/ng/areq?p0=Missing&p1=not%20a%20function,%20got%20undefined'); expect(element(by.css('.minerr-errmsg')).getText()).toEqual("Argument 'Missing' is not a function, got undefined"); }); + + + it("should display an error if the page does not exist", function() { + browser.get('index-debug.html#!/api/does/not/exist'); + expect(element(by.css('h1')).getText()).toBe('Oops!'); + }); }); describe("templates", function() { @@ -76,13 +67,4 @@ describe('docs.angularjs.org', function () { }); }); - describe("API pages", function() { - it("should display links to code on GitHub", function() { - browser.get('index-debug.html#!/api/ng/service/$http'); - expect(element(by.css('.improve-docs')).getAttribute('href')).toMatch(/https?:\/\/github\.com\/angular\/angular\.js\/edit\/.+\/src\/ng\/http\.js/); - - browser.get('index-debug.html#!/api/ng/service/$http'); - expect(element(by.css('.view-source')).getAttribute('href')).toMatch(/https?:\/\/github\.com\/angular\/angular\.js\/tree\/.+\/src\/ng\/http\.js#L\d+/); - }); - }); }); diff --git a/docs/protractor-conf.js b/docs/protractor-conf.js new file mode 100644 index 000000000000..490b46fc5960 --- /dev/null +++ b/docs/protractor-conf.js @@ -0,0 +1,13 @@ +'use strict'; + +var config = require('../protractor-shared-conf').config; + +config.specs = [ + 'app/e2e/*.scenario.js' +]; + +config.capabilities = { + browserName: 'chrome', +}; + +exports.config = config; diff --git a/protractor-conf.js b/protractor-conf.js index d2a204b11aca..658680b9e6e0 100644 --- a/protractor-conf.js +++ b/protractor-conf.js @@ -4,7 +4,7 @@ var config = require('./protractor-shared-conf').config; config.specs = [ 'build/docs/ptore2e/**/*.js', - 'docs/app/e2e/docsAppE2E.js' + 'docs/app/e2e/*.scenario.js' ]; config.capabilities = { diff --git a/protractor-jenkins-conf.js b/protractor-jenkins-conf.js index 09d6bc1145a4..f0aaa0528982 100644 --- a/protractor-jenkins-conf.js +++ b/protractor-jenkins-conf.js @@ -5,7 +5,7 @@ exports.config = { specs: [ 'build/docs/ptore2e/**/*.js', - 'docs/app/e2e/docsAppE2E.js' + 'docs/app/e2e/*.scenario.js' ], capabilities: { diff --git a/scripts/travis/build.sh b/scripts/travis/build.sh index 41739650ae86..942c34ecdcf8 100755 --- a/scripts/travis/build.sh +++ b/scripts/travis/build.sh @@ -9,7 +9,7 @@ if [ $JOB = "unit" ]; then grunt test:promises-aplus grunt test:unit --browsers SL_Chrome,SL_Safari,SL_Firefox,SL_IE_8,SL_IE_9,SL_IE_10,SL_IE_11 --reporters dots grunt tests:docs --browsers SL_Chrome,SL_Safari,SL_Firefox,SL_IE_8,SL_IE_9,SL_IE_10,SL_IE_11 --reporters dots - grunt test:travis-protractor --specs "docs/app/e2e/docsAppE2E.js" + grunt test:travis-protractor --specs "docs/app/e2e/*.scenario.js" elif [ $JOB = "e2e" ]; then export TARGET_SPECS="build/docs/ptore2e/**/default_test.js" if [ $TEST_TARGET = "jquery" ]; then From b4de7307c376d54b0245b2e0e48fd6467ce56fdd Mon Sep 17 00:00:00 2001 From: Peter Bacon Darwin Date: Fri, 12 Sep 2014 23:04:35 +0100 Subject: [PATCH 3/8] test(docs): add extra docs e2e tests --- .../e2e/{ => api-docs}/api-pages.scenario.js | 0 .../e2e/api-docs/provider-pages.scenario.js | 12 ++++++++++ .../e2e/api-docs/service-pages.scenario.js | 22 +++++++++++++++++++ docs/app/e2e/app.scenario.js | 7 ------ 4 files changed, 34 insertions(+), 7 deletions(-) rename docs/app/e2e/{ => api-docs}/api-pages.scenario.js (100%) create mode 100644 docs/app/e2e/api-docs/provider-pages.scenario.js create mode 100644 docs/app/e2e/api-docs/service-pages.scenario.js diff --git a/docs/app/e2e/api-pages.scenario.js b/docs/app/e2e/api-docs/api-pages.scenario.js similarity index 100% rename from docs/app/e2e/api-pages.scenario.js rename to docs/app/e2e/api-docs/api-pages.scenario.js diff --git a/docs/app/e2e/api-docs/provider-pages.scenario.js b/docs/app/e2e/api-docs/provider-pages.scenario.js new file mode 100644 index 000000000000..02e7bcde8586 --- /dev/null +++ b/docs/app/e2e/api-docs/provider-pages.scenario.js @@ -0,0 +1,12 @@ +'use strict'; + +describe("provider pages", function() { + + it("should show the related service", function() { + browser.get('index-debug.html#!/api/ng/provider/$compileProvider'); + var serviceLink = element.all(by.css('ol.api-profile-header-structure li a')).first(); + expect(serviceLink.getText()).toEqual('- $compile'); + expect(serviceLink.getAttribute('href')).toMatch('api/ng/service/$compile'); + }); + +}); \ No newline at end of file diff --git a/docs/app/e2e/api-docs/service-pages.scenario.js b/docs/app/e2e/api-docs/service-pages.scenario.js new file mode 100644 index 000000000000..18d12623ae9f --- /dev/null +++ b/docs/app/e2e/api-docs/service-pages.scenario.js @@ -0,0 +1,22 @@ +'use strict'; + +describe("service pages", function() { + + it("should show the related provider if there is one", function() { + browser.get('index-debug.html#!/api/ng/service/$compile'); + var providerLink = element.all(by.css('ol.api-profile-header-structure li a')).first(); + expect(providerLink.getText()).toEqual('- $compileProvider'); + expect(providerLink.getAttribute('href')).toMatch('api/ng/provider/$compileProvider'); + + browser.get('index-debug.html#!/api/ng/service/$q'); + providerLink = element.all(by.css('ol.api-profile-header-structure li a')).first(); + expect(providerLink.getText()).not.toEqual('- $qProvider'); + expect(providerLink.getAttribute('href')).not.toMatch('api/ng/provider/$compileProvider'); + }); + + it("should show parameter defaults", function() { + browser.get('index-debug.html#!/api/ng/service/$timeout'); + expect(element.all(by.css('.input-arguments p em')).first().getText()).toContain('(default: 0)'); + }); + +}); \ No newline at end of file diff --git a/docs/app/e2e/app.scenario.js b/docs/app/e2e/app.scenario.js index ef063980d558..539e7f1036b5 100644 --- a/docs/app/e2e/app.scenario.js +++ b/docs/app/e2e/app.scenario.js @@ -60,11 +60,4 @@ describe('docs.angularjs.org', function () { }); }); - describe("templates", function() { - it("should show parameter defaults", function() { - browser.get('index-debug.html#!/api/ng/service/$timeout'); - expect(element.all(by.css('.input-arguments p em')).first().getText()).toContain('(default: 0)'); - }); - }); - }); From bf24ad144df189007e9ef4f8493bf1f41c93427c Mon Sep 17 00:00:00 2001 From: Peter Bacon Darwin Date: Mon, 15 Sep 2014 20:38:50 +0100 Subject: [PATCH 4/8] docs(ngShowHide): use backticks to denote CSS classes and directive names add backticks around directive names to improve documentation consistency, as it's used in some parts of the docs already. Closes #9081 --- src/ng/directive/ngShowHide.js | 34 +++++++++++++++++----------------- 1 file changed, 17 insertions(+), 17 deletions(-) diff --git a/src/ng/directive/ngShowHide.js b/src/ng/directive/ngShowHide.js index a35fceee7aea..bd6add39368a 100644 --- a/src/ng/directive/ngShowHide.js +++ b/src/ng/directive/ngShowHide.js @@ -6,8 +6,8 @@ * * @description * The `ngShow` directive shows or hides the given HTML element based on the expression - * provided to the ngShow attribute. The element is shown or hidden by removing or adding - * the `ng-hide` CSS class onto the element. The `.ng-hide` CSS class is predefined + * provided to the `ngShow` attribute. The element is shown or hidden by removing or adding + * the `.ng-hide` CSS class onto the element. The `.ng-hide` CSS class is predefined * in AngularJS and sets the display style to none (using an !important flag). * For CSP mode please add `angular-csp.css` to your html file (see {@link ng.directive:ngCsp ngCsp}). * @@ -19,8 +19,8 @@ *
* ``` * - * When the ngShow expression evaluates to false then the ng-hide CSS class is added to the class attribute - * on the element causing it to become hidden. When true, the ng-hide CSS class is removed + * When the `ngShow` expression evaluates to false then the `.ng-hide` CSS class is added to the class attribute + * on the element causing it to become hidden. When true, the `.ng-hide` CSS class is removed * from the element causing the element not to appear hidden. * *
@@ -30,7 +30,7 @@ * * ## Why is !important used? * - * You may be wondering why !important is used for the .ng-hide CSS class. This is because the `.ng-hide` selector + * You may be wondering why !important is used for the `.ng-hide` CSS class. This is because the `.ng-hide` selector * can be easily overridden by heavier selectors. For example, something as simple * as changing the display style on a HTML list item would make hidden elements appear visible. * This also becomes a bigger issue when dealing with CSS frameworks. @@ -39,7 +39,7 @@ * specificity (when !important isn't used with any conflicting styles). If a developer chooses to override the * styling to change how to hide an element then it is just a matter of using !important in their own CSS code. * - * ### Overriding .ng-hide + * ### Overriding `.ng-hide` * * By default, the `.ng-hide` class will style the element with `display:none!important`. If you wish to change * the hide behavior with ngShow/ngHide then this can be achieved by restating the styles for the `.ng-hide` @@ -57,7 +57,7 @@ * * By default you don't need to override in CSS anything and the animations will work around the display style. * - * ## A note about animations with ngShow + * ## A note about animations with `ngShow` * * Animations in ngShow/ngHide work with the show and hide events that are triggered when the directive expression * is true and false. This system works like the animation system present with ngClass except that @@ -82,8 +82,8 @@ * property to block during animation states--ngAnimate will handle the style toggling automatically for you. * * @animations - * addClass: .ng-hide - happens after the ngShow expression evaluates to a truthy value and the just before contents are set to visible - * removeClass: .ng-hide - happens after the ngShow expression evaluates to a non truthy value and just before the contents are set to hidden + * addClass: `.ng-hide` - happens after the `ngShow` expression evaluates to a truthy value and the just before contents are set to visible + * removeClass: `.ng-hide` - happens after the `ngShow` expression evaluates to a non truthy value and just before the contents are set to hidden * * @element ANY * @param {expression} ngShow If the {@link guide/expression expression} is truthy @@ -163,7 +163,7 @@ var ngShowDirective = ['$animate', function($animate) { * * @description * The `ngHide` directive shows or hides the given HTML element based on the expression - * provided to the ngHide attribute. The element is shown or hidden by removing or adding + * provided to the `ngHide` attribute. The element is shown or hidden by removing or adding * the `ng-hide` CSS class onto the element. The `.ng-hide` CSS class is predefined * in AngularJS and sets the display style to none (using an !important flag). * For CSP mode please add `angular-csp.css` to your html file (see {@link ng.directive:ngCsp ngCsp}). @@ -176,8 +176,8 @@ var ngShowDirective = ['$animate', function($animate) { *
* ``` * - * When the ngHide expression evaluates to true then the .ng-hide CSS class is added to the class attribute - * on the element causing it to become hidden. When false, the ng-hide CSS class is removed + * When the `.ngHide` expression evaluates to true then the `.ng-hide` CSS class is added to the class attribute + * on the element causing it to become hidden. When false, the `.ng-hide` CSS class is removed * from the element causing the element not to appear hidden. * *
@@ -187,7 +187,7 @@ var ngShowDirective = ['$animate', function($animate) { * * ## Why is !important used? * - * You may be wondering why !important is used for the .ng-hide CSS class. This is because the `.ng-hide` selector + * You may be wondering why !important is used for the `.ng-hide` CSS class. This is because the `.ng-hide` selector * can be easily overridden by heavier selectors. For example, something as simple * as changing the display style on a HTML list item would make hidden elements appear visible. * This also becomes a bigger issue when dealing with CSS frameworks. @@ -196,7 +196,7 @@ var ngShowDirective = ['$animate', function($animate) { * specificity (when !important isn't used with any conflicting styles). If a developer chooses to override the * styling to change how to hide an element then it is just a matter of using !important in their own CSS code. * - * ### Overriding .ng-hide + * ### Overriding `.ng-hide` * * By default, the `.ng-hide` class will style the element with `display:none!important`. If you wish to change * the hide behavior with ngShow/ngHide then this can be achieved by restating the styles for the `.ng-hide` @@ -214,7 +214,7 @@ var ngShowDirective = ['$animate', function($animate) { * * By default you don't need to override in CSS anything and the animations will work around the display style. * - * ## A note about animations with ngHide + * ## A note about animations with `ngHide` * * Animations in ngShow/ngHide work with the show and hide events that are triggered when the directive expression * is true and false. This system works like the animation system present with ngClass, except that the `.ng-hide` @@ -238,8 +238,8 @@ var ngShowDirective = ['$animate', function($animate) { * property to block during animation states--ngAnimate will handle the style toggling automatically for you. * * @animations - * removeClass: .ng-hide - happens after the ngHide expression evaluates to a truthy value and just before the contents are set to hidden - * addClass: .ng-hide - happens after the ngHide expression evaluates to a non truthy value and just before the contents are set to visible + * removeClass: `.ng-hide` - happens after the `ngHide` expression evaluates to a truthy value and just before the contents are set to hidden + * addClass: `.ng-hide` - happens after the `ngHide` expression evaluates to a non truthy value and just before the contents are set to visible * * @element ANY * @param {expression} ngHide If the {@link guide/expression expression} is truthy then From c4d3e6fd43566810adb31a4ea9c18c15c441a3ef Mon Sep 17 00:00:00 2001 From: Peter Bacon Darwin Date: Mon, 15 Sep 2014 20:39:36 +0100 Subject: [PATCH 5/8] chore(docs): ensure all docs e2e tests are run --- docs/protractor-conf.js | 2 +- protractor-conf.js | 2 +- scripts/travis/build.sh | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/protractor-conf.js b/docs/protractor-conf.js index 490b46fc5960..e85d509a9d52 100644 --- a/docs/protractor-conf.js +++ b/docs/protractor-conf.js @@ -3,7 +3,7 @@ var config = require('../protractor-shared-conf').config; config.specs = [ - 'app/e2e/*.scenario.js' + 'app/e2e/**/*.scenario.js' ]; config.capabilities = { diff --git a/protractor-conf.js b/protractor-conf.js index 658680b9e6e0..577d8b2b10ec 100644 --- a/protractor-conf.js +++ b/protractor-conf.js @@ -4,7 +4,7 @@ var config = require('./protractor-shared-conf').config; config.specs = [ 'build/docs/ptore2e/**/*.js', - 'docs/app/e2e/*.scenario.js' + 'docs/app/e2e/**/*.scenario.js' ]; config.capabilities = { diff --git a/scripts/travis/build.sh b/scripts/travis/build.sh index 942c34ecdcf8..2c642355f7b7 100755 --- a/scripts/travis/build.sh +++ b/scripts/travis/build.sh @@ -9,7 +9,7 @@ if [ $JOB = "unit" ]; then grunt test:promises-aplus grunt test:unit --browsers SL_Chrome,SL_Safari,SL_Firefox,SL_IE_8,SL_IE_9,SL_IE_10,SL_IE_11 --reporters dots grunt tests:docs --browsers SL_Chrome,SL_Safari,SL_Firefox,SL_IE_8,SL_IE_9,SL_IE_10,SL_IE_11 --reporters dots - grunt test:travis-protractor --specs "docs/app/e2e/*.scenario.js" + grunt test:travis-protractor --specs "docs/app/e2e/**/*.scenario.js" elif [ $JOB = "e2e" ]; then export TARGET_SPECS="build/docs/ptore2e/**/default_test.js" if [ $TEST_TARGET = "jquery" ]; then From dea705b2cf1f62342abb3d990d08c98fbc5dbf62 Mon Sep 17 00:00:00 2001 From: Peter Bacon Darwin Date: Mon, 15 Sep 2014 14:55:42 +0100 Subject: [PATCH 6/8] test(docs): fix url matching on api e2e tests --- docs/app/e2e/api-docs/provider-pages.scenario.js | 2 +- docs/app/e2e/api-docs/service-pages.scenario.js | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/app/e2e/api-docs/provider-pages.scenario.js b/docs/app/e2e/api-docs/provider-pages.scenario.js index 02e7bcde8586..24d6bfdef8b9 100644 --- a/docs/app/e2e/api-docs/provider-pages.scenario.js +++ b/docs/app/e2e/api-docs/provider-pages.scenario.js @@ -6,7 +6,7 @@ describe("provider pages", function() { browser.get('index-debug.html#!/api/ng/provider/$compileProvider'); var serviceLink = element.all(by.css('ol.api-profile-header-structure li a')).first(); expect(serviceLink.getText()).toEqual('- $compile'); - expect(serviceLink.getAttribute('href')).toMatch('api/ng/service/$compile'); + expect(serviceLink.getAttribute('href')).toMatch(/api\/ng\/service\/\$compile/); }); }); \ No newline at end of file diff --git a/docs/app/e2e/api-docs/service-pages.scenario.js b/docs/app/e2e/api-docs/service-pages.scenario.js index 18d12623ae9f..a26dd5ef2755 100644 --- a/docs/app/e2e/api-docs/service-pages.scenario.js +++ b/docs/app/e2e/api-docs/service-pages.scenario.js @@ -6,12 +6,12 @@ describe("service pages", function() { browser.get('index-debug.html#!/api/ng/service/$compile'); var providerLink = element.all(by.css('ol.api-profile-header-structure li a')).first(); expect(providerLink.getText()).toEqual('- $compileProvider'); - expect(providerLink.getAttribute('href')).toMatch('api/ng/provider/$compileProvider'); + expect(providerLink.getAttribute('href')).toMatch(/api\/ng\/provider\/\$compileProvider/); browser.get('index-debug.html#!/api/ng/service/$q'); providerLink = element.all(by.css('ol.api-profile-header-structure li a')).first(); expect(providerLink.getText()).not.toEqual('- $qProvider'); - expect(providerLink.getAttribute('href')).not.toMatch('api/ng/provider/$compileProvider'); + expect(providerLink.getAttribute('href')).not.toMatch(/api\/ng\/provider\/\$compileProvider/); }); it("should show parameter defaults", function() { From 9cc968689f6e0627f43e2193e379c9972935c586 Mon Sep 17 00:00:00 2001 From: Peter Bacon Darwin Date: Mon, 15 Sep 2014 14:57:07 +0100 Subject: [PATCH 7/8] chore(docs): remove excess indentation from code blocks dgeni-packages 0.10.0-rc.5 has a fix for this problem, so this commit updates to that version. Adds a new e2e test to prove this is fixed. Closes #8963 --- docs/app/e2e/api-docs/api-pages.scenario.js | 10 +++++ npm-shrinkwrap.json | 43 +++------------------ 2 files changed, 15 insertions(+), 38 deletions(-) diff --git a/docs/app/e2e/api-docs/api-pages.scenario.js b/docs/app/e2e/api-docs/api-pages.scenario.js index 76ee7a1165f3..2695971ca483 100644 --- a/docs/app/e2e/api-docs/api-pages.scenario.js +++ b/docs/app/e2e/api-docs/api-pages.scenario.js @@ -37,5 +37,15 @@ describe("doc.angularjs.org", function() { var code = element.all(by.css('tt')).first(); expect(code.getText()).toContain('guest!!!'); }); + + it("should trim indentation from code blocks", function() { + browser.get('index-debug.html#!/api/ng/type/$rootScope.Scope'); + + var codeBlocks = element.all(by.css('pre > code.lang-js')); + codeBlocks.each(function(codeBlock) { + var firstSpan = codeBlock.all(by.css('span')).first(); + expect(firstSpan.getText()).not.toMatch(/^\W+$/); + }); + }); }); }); \ No newline at end of file diff --git a/npm-shrinkwrap.json b/npm-shrinkwrap.json index 71da46a26a14..081a35589738 100644 --- a/npm-shrinkwrap.json +++ b/npm-shrinkwrap.json @@ -1142,7 +1142,7 @@ } }, "dgeni-packages": { - "version": "0.10.0-rc.3", + "version": "0.10.0-rc.5", "dependencies": { "catharsis": { "version": "0.7.1" @@ -1197,42 +1197,12 @@ } } }, - "dgeni": { - "version": "0.4.0-rc.2", - "dependencies": { - "dependency-graph": { - "version": "0.1.0", - "dependencies": { - "underscore": { - "version": "1.4.4" - } - } - }, - "di": { - "version": "0.0.1" - }, - "optimist": { - "version": "0.6.1", - "dependencies": { - "wordwrap": { - "version": "0.0.2" - }, - "minimist": { - "version": "0.0.10" - } - } - }, - "q": { - "version": "0.9.7" - }, - "validate.js": { - "version": "0.2.0" - } - } - }, "esprima": { "version": "1.2.2" }, + "estraverse": { + "version": "1.5.1" + }, "glob": { "version": "3.2.11", "dependencies": { @@ -1244,9 +1214,6 @@ "lodash": { "version": "2.4.1" }, - "marked": { - "version": "0.2.10" - }, "minimatch": { "version": "0.3.0", "dependencies": { @@ -1725,7 +1692,7 @@ }, "grunt-jasmine-node": { "version": "0.1.0", - "from": "grunt-jasmine-node@git://github.com/vojtajina/grunt-jasmine-node.git#fix-grunt-exit-code", + "from": "grunt-jasmine-node@git://github.com/vojtajina/grunt-jasmine-node.git#ced17cbe52c1412b2ada53160432a5b681f37cd7", "resolved": "git://github.com/vojtajina/grunt-jasmine-node.git#ced17cbe52c1412b2ada53160432a5b681f37cd7" }, "grunt-jscs-checker": { From e251db9fb307b31b96e15e50cfc803db095269fc Mon Sep 17 00:00:00 2001 From: Peter Bacon Darwin Date: Mon, 15 Sep 2014 17:09:37 +0100 Subject: [PATCH 8/8] docs(ngView): remove obsolete comment from code sample Closes #9086 --- src/ngRoute/directive/ngView.js | 1 - 1 file changed, 1 deletion(-) diff --git a/src/ngRoute/directive/ngView.js b/src/ngRoute/directive/ngView.js index 85049d4a3163..97f253c21014 100644 --- a/src/ngRoute/directive/ngView.js +++ b/src/ngRoute/directive/ngView.js @@ -134,7 +134,6 @@ ngRouteModule.directive('ngView', ngViewFillContentFactory); controllerAs: 'chapter' }); - // configure html5 to get links working on jsfiddle $locationProvider.html5Mode(true); }]) .controller('MainCtrl', ['$route', '$routeParams', '$location',