iSharkFly-Docs
/
angular-docs-cn
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

refactor(checkUnbalancedTicks): split out convertBackticksToCodeBlocks to maintain cohesion 

This improves upon changes made in 28a805733f6bd8b3a3394ea29c828c17b391c855
as part of #277
This commit is contained in:
Peter Bacon Darwin 2015-10-17 08:45:56 +01:00 committed by Jay Traband
parent 23452bffa0
commit 3baf6c0561
5 changed files with 155 additions and 46 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
public/api-builder/docs-package/index.js
View File

@ -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) {

48
public/api-builder/docs-package/processors/checkUnbalancedBackTicks.js
View File

@ -1,14 +1,5 @@
var _ = require('lodash');
function escapeHtml(unsafe) {
return unsafe
.replace(/&/g, "&")
.replace(/</g, "&lt;")
.replace(/>/g, "&gt;")
.replace(/"/g, "&quot;")
.replace(/'/g, "&#039;");
}
/**
* @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);
}
}
});

32
public/api-builder/docs-package/processors/checkUnbalancedBackTicks.spec.js Normal file
View File

@ -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);
});
});

61
public/api-builder/docs-package/processors/convertBackticksToCodeBlocks.js Normal file
View File

@ -0,0 +1,61 @@
var _ = require('lodash');
function escapeHtml(unsafe) {
return unsafe
.replace(/&/g, "&amp;")
.replace(/</g, "&lt;")
.replace(/>/g, "&gt;")
.replace(/"/g, "&quot;")
.replace(/'/g, "&#039;");
}
// 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);
}
}
});
}
};
};

59
public/api-builder/docs-package/processors/convertBackticksToCodeBlocks.spec.js Normal file
View File

@ -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'
);
})
});