diff --git a/public/api-builder/docs-package/index.js b/public/api-builder/docs-package/index.js index f931b9dd33..76fea69320 100644 --- a/public/api-builder/docs-package/index.js +++ b/public/api-builder/docs-package/index.js @@ -19,6 +19,7 @@ module.exports = new Package('angular-v2-docs', [jsdocPackage, nunjucksPackage, .processor(require('./processors/extractTitleFromGuides')) .processor(require('./processors/createOverviewDump')) .processor(require('./processors/checkUnbalancedBackTicks')) +.processor(require('./processors/convertBackTicksToCodeBlocks')) // Configure the log service .config(function(log) { diff --git a/public/api-builder/docs-package/processors/checkUnbalancedBackTicks.js b/public/api-builder/docs-package/processors/checkUnbalancedBackTicks.js index 3e75596584..590015350d 100644 --- a/public/api-builder/docs-package/processors/checkUnbalancedBackTicks.js +++ b/public/api-builder/docs-package/processors/checkUnbalancedBackTicks.js @@ -1,14 +1,5 @@ var _ = require('lodash'); -function escapeHtml(unsafe) { - return unsafe - .replace(/&/g, "&") - .replace(//g, ">") - .replace(/"/g, """) - .replace(/'/g, "'"); -} - /** * @dgProcessor checkUnbalancedBackTicks * @description @@ -19,17 +10,7 @@ function escapeHtml(unsafe) { module.exports = function checkUnbalancedBackTicks(log, createDocMessage) { var BACKTICK_REGEX = /^ *```/gm; - - // captures below - // 1st is entire ``` including leading whitespace - // 2nd is the leading whitespace on the line before the ``` fence - // 3rd is the name of the language (if any) specified after the ``` - // 4th is the contents of the ``` block up until but not including the first non whitespace char after the end ``` - // 5th is the padding of the first nonblank line following the backtick block - // 6th is the first char on the next line. - var BACKTICK_CAPTURE = /(( *)```(.*$)([^]*?)```\s*)^(\s*)(\S)/m; - var CODE_EXAMPLE = 'code-example(format="linenums" language="js").'; return { // $runAfter: ['checkAnchorLinksProcessor'], $runAfter: ['inlineTagProcessor'], @@ -39,34 +20,9 @@ module.exports = function checkUnbalancedBackTicks(log, createDocMessage) { if ( doc.renderedContent ) { var matches = doc.renderedContent.match(BACKTICK_REGEX); if (matches && matches.length % 2 !== 0) { + doc.unbalancedBackTicks = true; log.warn(createDocMessage('checkUnbalancedBackTicks processor: unbalanced backticks found in rendered content', doc)); - console.log(doc.renderedContent); - } else if (matches) { - // Idea here is to translate backtic ``` regions into code-example blocks. - var captures = BACKTICK_CAPTURE.exec(doc.renderedContent); - while (captures) { - var entireBlock = captures[1]; - var prePad = captures[2]; - var language = captures[3]; - var blockContents = captures[4]; - var postPad = captures[5]; - var nextBlockStartChar = captures[6]; - var codeExamplePrefix = language.length ? CODE_EXAMPLE.replace('js', language) : CODE_EXAMPLE; - // modulo op in next line insures that pad is always a multiple of 2 ( jade whitespace). - var newPrePad = prePad.substr(2 + (prePad.length % 2)); // exdent - var replaceVal = '\n' + newPrePad + codeExamplePrefix + escapeHtml(blockContents) + '\n'; - // if nextBlock does NOT start with a '.' then we want to restart a markdown block. - // and that block needs to be exdented from the preceding code-example content. - if (nextBlockStartChar != '.') { - if (postPad.length >= 2) { - // modulo op in next line insures that pad is always a multiple of 2 ( jade whitespace). - postPad = postPad.substr(2 + (postPad.length % 2)); // exdent - } - replaceVal = replaceVal + postPad + ':markdown\n'; - } - doc.renderedContent = doc.renderedContent.replace(entireBlock, replaceVal); - captures = BACKTICK_CAPTURE.exec(doc.renderedContent); - } + log.warn(doc.renderedContent); } } }); diff --git a/public/api-builder/docs-package/processors/checkUnbalancedBackTicks.spec.js b/public/api-builder/docs-package/processors/checkUnbalancedBackTicks.spec.js new file mode 100644 index 0000000000..14ba8e2d6b --- /dev/null +++ b/public/api-builder/docs-package/processors/checkUnbalancedBackTicks.spec.js @@ -0,0 +1,32 @@ +var mockPackage = require('../mocks/mockPackage'); +var Dgeni = require('dgeni'); +var path = require('canonical-path'); +var _ = require('lodash'); + +describe('checkUnbalancedBackTicks', function() { + var dgeni, injector, processor, log; + + beforeEach(function() { + dgeni = new Dgeni([mockPackage()]); + injector = dgeni.configureInjector(); + processor = injector.get('checkUnbalancedBackTicks'); + log = injector.get('log'); + }); + + it('should warn if there are an odd number of back ticks in the rendered content', function() { + var docs = [ + { renderedContent: + '```\n' + + 'code block\n' + + '```\n' + + '```\n' + + 'code block with missing closing back ticks\n' + } + ]; + + processor.$process(docs); + + expect(log.warn).toHaveBeenCalledWith('checkUnbalancedBackTicks processor: unbalanced backticks found in rendered content - doc'); + expect(docs[0].unbalancedBackTicks).toBe(true); + }); +}); \ No newline at end of file diff --git a/public/api-builder/docs-package/processors/convertBackticksToCodeBlocks.js b/public/api-builder/docs-package/processors/convertBackticksToCodeBlocks.js new file mode 100644 index 0000000000..1368f43b13 --- /dev/null +++ b/public/api-builder/docs-package/processors/convertBackticksToCodeBlocks.js @@ -0,0 +1,61 @@ +var _ = require('lodash'); + +function escapeHtml(unsafe) { + return unsafe + .replace(/&/g, "&") + .replace(//g, ">") + .replace(/"/g, """) + .replace(/'/g, "'"); +} + + +// captures below +// 1st is entire ``` including leading whitespace +// 2nd is the leading whitespace on the line before the ``` fence +// 3rd is the name of the language (if any) specified after the ``` +// 4th is the contents of the ``` block up until but not including the first non whitespace char after the end ``` +// 5th is the padding of the first nonblank line following the backtick block +// 6th is the first char on the next line. +var BACKTICK_CAPTURE = /(( *)```(.*$)([^]*?)```\s*)^(\s*)(\S)/m; + +var CODE_EXAMPLE = 'code-example(format="linenums" language="js").'; + +module.exports = function convertBackticksToCodeBlocks() { + return { + $runAfter: ['checkUnbalancedBackTicks'], + $runBefore: ['writeFilesProcessor'], + $process: function(docs) { + _.forEach(docs, function(doc) { + if (!doc.unbalancedBackTicks) { + + // Idea here is to translate backtick ``` regions into code-example blocks. + var captures = BACKTICK_CAPTURE.exec(doc.renderedContent); + while (captures) { + var entireBlock = captures[1]; + var prePad = captures[2]; + var language = captures[3]; + var blockContents = captures[4]; + var postPad = captures[5]; + var nextBlockStartChar = captures[6]; + var codeExamplePrefix = language.length ? CODE_EXAMPLE.replace('js', language) : CODE_EXAMPLE; + // modulo op in next line insures that pad is always a multiple of 2 ( jade whitespace). + var newPrePad = prePad.substr(2 + (prePad.length % 2)); // exdent + var replaceVal = '\n' + newPrePad + codeExamplePrefix + escapeHtml(blockContents) + '\n'; + // if nextBlock does NOT start with a '.' then we want to restart a markdown block. + // and that block needs to be exdented from the preceding code-example content. + if (nextBlockStartChar != '.') { + if (postPad.length >= 2) { + // modulo op in next line insures that pad is always a multiple of 2 ( jade whitespace). + postPad = postPad.substr(2 + (postPad.length % 2)); // exdent + } + replaceVal = replaceVal + postPad + ':markdown\n'; + } + doc.renderedContent = doc.renderedContent.replace(entireBlock, replaceVal); + captures = BACKTICK_CAPTURE.exec(doc.renderedContent); + } + } + }); + } + }; +}; \ No newline at end of file diff --git a/public/api-builder/docs-package/processors/convertBackticksToCodeBlocks.spec.js b/public/api-builder/docs-package/processors/convertBackticksToCodeBlocks.spec.js new file mode 100644 index 0000000000..a2c31279cc --- /dev/null +++ b/public/api-builder/docs-package/processors/convertBackticksToCodeBlocks.spec.js @@ -0,0 +1,59 @@ +var mockPackage = require('../mocks/mockPackage'); +var Dgeni = require('dgeni'); +var path = require('canonical-path'); +var _ = require('lodash'); + +describe('convertBackticksToCodeBlocks', function() { + var dgeni, injector, processor; + + beforeEach(function() { + dgeni = new Dgeni([mockPackage()]); + injector = dgeni.configureInjector(); + processor = injector.get('convertBackticksToCodeBlocks'); + }); + + it('should convert backtick code blocks to code-example blocks', function() { + var docs = [{ + renderedContent: + 'preamble\n' + + '```ts\n' + + 'export class TypeScriptClass {\n' + + '}\n' + + '```\n' + + 'postamble\n' + }]; + processor.$process(docs); + expect(docs[0].renderedContent).toEqual( + 'preamble\n' + + '\n' + + 'code-example(format="linenums" language="ts").\n' + + 'export class TypeScriptClass {\n' + + '}\n' + + '\n' + + ':markdown\n' + + 'postamble\n' + ); + }); + + + it('should ignore docs that have been marked as having unbalanced backticks', function() { + var docs = [{ + renderedContent: + 'preamble\n' + + '```ts\n' + + 'export class TypeScriptClass {\n' + + '}\n' + + 'postamble\n' + }]; + processor.$process(docs); + + expect(docs[0].renderedContent).toEqual( + 'preamble\n' + + '```ts\n' + + 'export class TypeScriptClass {\n' + + '}\n' + + 'postamble\n' + ); + }) +}); +