diff --git a/gulpfile.js b/gulpfile.js index dc10189b26..3794ea5c06 100644 --- a/gulpfile.js +++ b/gulpfile.js @@ -403,7 +403,9 @@ gulp.task('add-example-boilerplate', function() { // copies boilerplate files to locations // where an example app is found -gulp.task('_copy-example-boilerplate', copyExampleBoilerplate); +gulp.task('_copy-example-boilerplate', function () { + if (!argv.fast) copyExampleBoilerplate(); +}); // copies boilerplate files to locations @@ -1036,7 +1038,7 @@ function buildApiDocs(targetLanguage) { try { // Build a specialized package to generate different versions of the API docs var package = new Package('apiDocs', [require(path.resolve(TOOLS_PATH, 'api-builder/angular.io-package'))]); - package.config(function(log, targetEnvironments, writeFilesProcessor, readTypeScriptModules) { + package.config(function(log, targetEnvironments, writeFilesProcessor, readTypeScriptModules, linkDocsInlineTagDef) { log.level = _dgeniLogLevel; ALLOWED_LANGUAGES.forEach(function(target) { targetEnvironments.addAllowed(target); }); if (targetLanguage) { @@ -1046,7 +1048,9 @@ function buildApiDocs(targetLanguage) { // Don't read TypeScript modules if we are not generating API docs - Dart I am looking at you! readTypeScriptModules.$enabled = false; } - writeFilesProcessor.outputFolder = targetLanguage + '/latest/api'; + linkDocsInlineTagDef.lang = targetLanguage; + linkDocsInlineTagDef.vers = 'latest'; + writeFilesProcessor.outputFolder = path.join(targetLanguage, linkDocsInlineTagDef.vers, 'api'); } }); diff --git a/tools/api-builder/links-package/index.js b/tools/api-builder/links-package/index.js index 3036c2441b..5391399055 100644 --- a/tools/api-builder/links-package/index.js +++ b/tools/api-builder/links-package/index.js @@ -3,7 +3,7 @@ var Package = require('dgeni').Package; module.exports = new Package('links', []) .factory(require('./inline-tag-defs/link')) -.factory(require('./inline-tag-defs/linkDevGuide')) +.factory(require('./inline-tag-defs/linkDocs')) .factory(require('./inline-tag-defs/example')) .factory(require('./inline-tag-defs/exampleTabs')) .factory(require('dgeni-packages/links/services/getAliases')) @@ -12,9 +12,9 @@ module.exports = new Package('links', []) .factory(require('./services/parseArgString')) .factory(require('./services/getApiFragmentFileName')) -.config(function(inlineTagProcessor, linkInlineTagDef, linkDevGuideInlineTagDef, exampleInlineTagDef, exampleTabsInlineTagDef) { +.config(function(inlineTagProcessor, linkInlineTagDef, linkDocsInlineTagDef, exampleInlineTagDef, exampleTabsInlineTagDef) { inlineTagProcessor.inlineTagDefinitions.push(linkInlineTagDef); - inlineTagProcessor.inlineTagDefinitions.push(linkDevGuideInlineTagDef); + inlineTagProcessor.inlineTagDefinitions.push(linkDocsInlineTagDef); inlineTagProcessor.inlineTagDefinitions.push(exampleInlineTagDef); inlineTagProcessor.inlineTagDefinitions.push(exampleTabsInlineTagDef); }); diff --git a/tools/api-builder/links-package/inline-tag-defs/example.js b/tools/api-builder/links-package/inline-tag-defs/example.js index caaccfd61f..1df3f0223f 100644 --- a/tools/api-builder/links-package/inline-tag-defs/example.js +++ b/tools/api-builder/links-package/inline-tag-defs/example.js @@ -40,18 +40,8 @@ module.exports = function exampleInlineTagDef(getLinkInfo, parseArgString, getAp }; }; -// Examples of what @example and @exampleTabs markup looks like in the angular/angular source. -//* -//* {@example core/application_spec.ts hello-app -title='Sample component' } -//* -//* {@exampleTabs core/application_spec.ts,core/application_spec.ts "hello-app,hello-app2" -titles="Hello app1, Hello app2" } -//* - - function quote(str) { if (str == null || str.length === 0) return str; str = str.replace("'","'\'"); return "'" + str + "'"; } - - diff --git a/tools/api-builder/links-package/inline-tag-defs/linkDevGuide.js b/tools/api-builder/links-package/inline-tag-defs/linkDevGuide.js deleted file mode 100644 index 1e40227e81..0000000000 --- a/tools/api-builder/links-package/inline-tag-defs/linkDevGuide.js +++ /dev/null @@ -1,53 +0,0 @@ -var path = require('canonical-path'); -var fs = require("fs"); -var jsonFile = require('jsonfile'); - -var INLINE_LINK = /(\S+)(?:\s+([\s\S]+))?/; - -/** - * @dgService linkDevGuideInlineTagDef - * @description - * Process inline link tags (of the form {@linkDevGuide some/uri 'Some Title'}), replacing them with HTML anchors. - * The uri should point to a jade page in the DevGuide without the .jade extension ( under public/docs ). - * If the title is omitted an attempt will be made to determine the title of the jade page being pointed to. If not found - * the the title will simply be the last part of the link. - * Examples - * {@linkDevGuide ts/latest/guide/gettingStarted } - * {@linkDevGuide js/latest/guide/gettingStarted 'Javascript version of getting started' } - * {@linkDevGuide ts/latest/guide/gettingStarted title="Typescript version of getting started" } - * @kind function - */ -module.exports = function linkDevGuideInlineTagDef(parseArgString, createDocMessage, log) { - return { - name: 'linkDevGuide', - description: 'Process inline link tags (of the form {@link some/uri "Some Title"}), replacing them with HTML anchors', - handler: function(doc, tagName, tagDescription) { - - // Parse out the uri and title - var tagArgs = parseArgString(tagDescription); - var unnamedArgs = tagArgs._; - var uri = unnamedArgs[0]; - var title = tagArgs.title || (unnamedArgs.length > 1 ? unnamedArgs[1] : null); - - var jadePath = path.join('./public/docs', uri + '.jade'); - var key = path.basename(jadePath, '.jade'); - if ( !fs.existsSync(jadePath)) { - log.warn(createDocMessage('Invalid DevGuide example (unable to locate jade file: "' + jadePath + '")', doc)); - } else { - if (!title) { - var jsonFilePath = path.join(path.dirname(jadePath), '_data.json'); - if ( fs.existsSync(jsonFilePath)) { - var jsonObj = jsonFile.readFileSync(jsonFilePath); - title = jsonObj[key] && jsonObj[key].title; - } - } - } - var url = path.join('/docs', uri + '.html'); - title = title || key || url; - - return "" + title + ""; - - } - }; -}; - diff --git a/tools/api-builder/links-package/inline-tag-defs/linkDocs.js b/tools/api-builder/links-package/inline-tag-defs/linkDocs.js new file mode 100644 index 0000000000..6254fc2d2f --- /dev/null +++ b/tools/api-builder/links-package/inline-tag-defs/linkDocs.js @@ -0,0 +1,75 @@ +var path = require('canonical-path'); +var fs = require("fs"); +var jsonFile = require('jsonfile'); + +/** + * @dgService linkDocsInlineTagDef + * @description + * Process inline link tags (of the form {@linkDocs some/uri 'Some Title'}), replacing them with HTML anchors. + * The uri should point to a jade page in the Docs without the .jade extension ( under public/docs ). + * If the title is omitted an attempt will be made to determine the title of the jade page being pointed to. If not found + * the the title will simply be the last part of the link. + * Examples + * {@linkDocs guide/gettingStarted 'QuickStart'} + * {@linkDocs ts/latest/guide/quickstart } + * {@linkDocs js/latest/guide/quickstart 'Javascript version of getting started' } + * {@linkDocs ts/latest/guide/quickstart title="Typescript version of getting started" } + * @kind function + * @property {string} lang Default docs API page language when not explicitly given in URI; one of ts|js|dart. + * @property {string} vers Default docs version. Currently only 'latest'. + */ +module.exports = function linkDocsInlineTagDef(parseArgString, createDocMessage, log) { + var _self = { + name: 'linkDocs', + lang: 'ts', + vers: 'latest', + description: 'Process inline link tags (of the form {@linkDocs some/uri [title=]"Some Title"}), replacing them with HTML anchors', + + handler: function(doc, tagName, tagDescription) { + // Parse out the uri and title + var tagArgs = parseArgString(tagDescription); + var unnamedArgs = tagArgs._; + var uri = unnamedArgs[0]; + var title = tagArgs.title || (unnamedArgs.length > 1 ? unnamedArgs[1] : null); + + // Are there parameters and/or an anchor? + var matches, paramAnchor = ''; + if (matches = uri.match(/([^\#\?]*)([\#\?].*)/)) { + uri = matches[1]; + paramAnchor = matches[2]; + } + + // Is this a chapter-relative uri like 'guide/...'? + if (!uri.match(/^(ts|js|dart)/)) { + var lang = _self.lang; + var vers = _self.vers; + var prevUri = uri; + uri = path.join(lang, vers, uri); + log.info('Ajusted linkDocs chapter-relative uri (' + doc.fileInfo.baseName + '): ' + prevUri + ' -> ' + uri); + } + + var isValid = false; + var jadePath = path.join('./public/docs', uri + '.jade'); + var key = path.basename(jadePath, '.jade'); + if ( !fs.existsSync(jadePath)) { + log.warn(createDocMessage('Invalid docs link (unable to locate jade file: "' + jadePath + '")', doc)); + } else { + isValid = true; + if (!title) { + var jsonFilePath = path.join(path.dirname(jadePath), '_data.json'); + if ( fs.existsSync(jsonFilePath)) { + var jsonObj = jsonFile.readFileSync(jsonFilePath); + title = jsonObj[key] && jsonObj[key].title; + } + } + } + var url = path.join('/docs', uri + '.html' + paramAnchor); + title = title || key || url; + + return isValid ? + '' + title + '' : + '' + title + ''; + } + }; + return _self; +};