cargdev/angular
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

style(docs-infra): reformat the auto-link-code files (#33877)

Browse Source 
PR Close #33877
This commit is contained in:
Pete Bacon Darwin 2019-11-16 22:18:34 +00:00 committed by Alex Rickabaugh
parent 5beae0633b
commit 526537fefe
2 changed files with 125 additions and 70 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

41
aio/tools/transforms/angular-base-package/post-processors/auto-link-code.js vendored
View File

@ -26,18 +26,17 @@ module.exports = function autoLinkCode(getDocFromAlias) {
autoLinkCodeImpl.codeElements = ['code']; autoLinkCodeImpl.codeElements = ['code'];
return autoLinkCodeImpl; return autoLinkCodeImpl;
function autoLinkCodeImpl() { function autoLinkCodeImpl() {
return (ast) => { return (ast) => {
visit(ast, 'element', (node, ancestors) => { visit(ast, 'element', (node, ancestors) => {
// Only interested in code elements that are not inside links // Only interested in code elements that are not inside links
if (autoLinkCodeImpl.codeElements.some(elementType => if (autoLinkCodeImpl.codeElements.some(elementType => is(node, elementType)) &&
is(node, elementType)) && (!node.properties.className ||
(!node.properties.className || node.properties.className.indexOf('no-auto-link') === -1) && node.properties.className.indexOf('no-auto-link') === -1) &&
ancestors.every(ancestor => !is(ancestor, 'a'))) { ancestors.every(ancestor => !is(ancestor, 'a'))) {
visit(node, 'text', (node, ancestors) => { visit(node, 'text', (node, ancestors) => {
// Only interested in text nodes that are not inside links // Only interested in text nodes that are not inside links
if (ancestors.every(ancestor => !is(ancestor, 'a'))) { if (ancestors.every(ancestor => !is(ancestor, 'a'))) {
const parent = ancestors[ancestors.length - 1]; const parent = ancestors[ancestors.length - 1];
const index = parent.children.indexOf(node); const index = parent.children.indexOf(node);
@ -47,15 +46,20 @@ module.exports = function autoLinkCode(getDocFromAlias) {
parent.children.splice(index, 1, createLinkNode(docs[0], node.value)); parent.children.splice(index, 1, createLinkNode(docs[0], node.value));
} else { } else {
// Parse the text for words that we can convert to links // Parse the text for words that we can convert to links
const nodes = textContent(node).split(/([A-Za-z0-9_.-]+)/) const nodes =
.filter(word => word.length) textContent(node)
.map((word, index, words) => { .split(/([A-Za-z0-9_.-]+)/)
// remove docs that fail the custom filter tests .filter(word => word.length)
const filteredDocs = autoLinkCodeImpl.customFilters.reduce((docs, filter) => filter(docs, words, index), getDocFromAlias(word)); .map((word, index, words) => {
return foundValidDoc(filteredDocs) ? // remove docs that fail the custom filter tests
createLinkNode(filteredDocs[0], word) : // Create a link wrapping the text node. const filteredDocs = autoLinkCodeImpl.customFilters.reduce(
{ type: 'text', value: word }; // this is just text so push a new text node (docs, filter) => filter(docs, words, index), getDocFromAlias(word));
}); return foundValidDoc(filteredDocs) ?
// Create a link wrapping the text node.
createLinkNode(filteredDocs[0], word) :
// this is just text so push a new text node
{type: 'text', value: word};
});
// Replace the text node with the links and leftover text nodes // Replace the text node with the links and leftover text nodes
Array.prototype.splice.apply(parent.children, [index, 1].concat(nodes)); Array.prototype.splice.apply(parent.children, [index, 1].concat(nodes));
@ -68,17 +72,16 @@ module.exports = function autoLinkCode(getDocFromAlias) {
} }
function foundValidDoc(docs) { function foundValidDoc(docs) {
return docs.length === 1 && return docs.length === 1 && !docs[0].internal &&
!docs[0].internal && autoLinkCodeImpl.docTypes.indexOf(docs[0].docType) !== -1;
autoLinkCodeImpl.docTypes.indexOf(docs[0].docType) !== -1;
} }
function createLinkNode(doc, text) { function createLinkNode(doc, text) {
return { return {
type: 'element', type: 'element',
tagName: 'a', tagName: 'a',
properties: { href: doc.path, class: 'code-anchor' }, properties: {href: doc.path, class: 'code-anchor'},
children: [{ type: 'text', value: text }] children: [{type: 'text', value: text}]
}; };
} }
}; };

154
aio/tools/transforms/angular-base-package/post-processors/auto-link-code.spec.js
View File

@ -18,101 +18,153 @@ describe('autoLinkCode post-processor', () => {
}); });
it('should insert an anchor into every code item that matches the id of an API doc', () => { it('should insert an anchor into every code item that matches the id of an API doc', () => {
aliasMap.addDoc({ docType: 'class', id: 'MyClass', aliases: ['MyClass'], path: 'a/b/myclass' }); aliasMap.addDoc({docType: 'class', id: 'MyClass', aliases: ['MyClass'], path: 'a/b/myclass'});
const doc = { docType: 'test-doc', renderedContent: '<code>MyClass</code>' }; const doc = {docType: 'test-doc', renderedContent: '<code>MyClass</code>'};
processor.$process([doc]); processor.$process([doc]);
expect(doc.renderedContent).toEqual('<code><a href="a/b/myclass" class="code-anchor">MyClass</a></code>'); expect(doc.renderedContent)
.toEqual('<code><a href="a/b/myclass" class="code-anchor">MyClass</a></code>');
}); });
it('should insert an anchor into every code item that matches an alias of an API doc', () => { it('should insert an anchor into every code item that matches an alias of an API doc', () => {
aliasMap.addDoc({ docType: 'class', id: 'MyClass', aliases: ['MyClass', 'foo.MyClass'], path: 'a/b/myclass' }); aliasMap.addDoc({
const doc = { docType: 'test-doc', renderedContent: '<code>foo.MyClass</code>' }; docType: 'class',
id: 'MyClass',
aliases: ['MyClass', 'foo.MyClass'],
path: 'a/b/myclass'
});
const doc = {docType: 'test-doc', renderedContent: '<code>foo.MyClass</code>'};
processor.$process([doc]); processor.$process([doc]);
expect(doc.renderedContent).toEqual('<code><a href="a/b/myclass" class="code-anchor">foo.MyClass</a></code>'); expect(doc.renderedContent)
.toEqual('<code><a href="a/b/myclass" class="code-anchor">foo.MyClass</a></code>');
}); });
it('should match code items within a block of code that contain a dot in their identifier', () => { it('should match code items within a block of code that contain a dot in their identifier',
aliasMap.addDoc({ docType: 'member', id: 'MyEnum.Value', aliases: ['Value', 'MyEnum.Value'], path: 'a/b/myenum' }); () => {
const doc = { docType: 'test-doc', renderedContent: '<code>someFn(): MyEnum.Value</code>' }; aliasMap.addDoc({
processor.$process([doc]); docType: 'member',
expect(doc.renderedContent).toEqual('<code>someFn(): <a href="a/b/myenum" class="code-anchor">MyEnum.Value</a></code>'); id: 'MyEnum.Value',
}); aliases: ['Value', 'MyEnum.Value'],
path: 'a/b/myenum'
});
const doc = {docType: 'test-doc', renderedContent: '<code>someFn(): MyEnum.Value</code>'};
processor.$process([doc]);
expect(doc.renderedContent)
.toEqual(
'<code>someFn(): <a href="a/b/myenum" class="code-anchor">MyEnum.Value</a></code>');
});
it('should ignore code items that do not match a link to an API doc', () => { it('should ignore code items that do not match a link to an API doc', () => {
aliasMap.addDoc({ docType: 'guide', id: 'MyClass', aliases: ['MyClass'], path: 'a/b/myclass' }); aliasMap.addDoc({docType: 'guide', id: 'MyClass', aliases: ['MyClass'], path: 'a/b/myclass'});
const doc = { docType: 'test-doc', renderedContent: '<code>MyClass</code>' }; const doc = {docType: 'test-doc', renderedContent: '<code>MyClass</code>'};
processor.$process([doc]); processor.$process([doc]);
expect(doc.renderedContent).toEqual('<code>MyClass</code>'); expect(doc.renderedContent).toEqual('<code>MyClass</code>');
}); });
it('should ignore code items that are already inside a link', () => { it('should ignore code items that are already inside a link', () => {
aliasMap.addDoc({ docType: 'class', id: 'MyClass', aliases: ['MyClass'], path: 'a/b/myclass' }); aliasMap.addDoc({docType: 'class', id: 'MyClass', aliases: ['MyClass'], path: 'a/b/myclass'});
const doc = { docType: 'test-doc', renderedContent: '<a href="..."><div><code>MyClass</code></div></a>' }; const doc = {
docType: 'test-doc',
renderedContent: '<a href="..."><div><code>MyClass</code></div></a>'
};
processor.$process([doc]); processor.$process([doc]);
expect(doc.renderedContent).toEqual('<a href="..."><div><code>MyClass</code></div></a>'); expect(doc.renderedContent).toEqual('<a href="..."><div><code>MyClass</code></div></a>');
}); });
it('should ignore code items match an API doc but are not in the list of acceptable docTypes', () => { it('should ignore code items match an API doc but are not in the list of acceptable docTypes',
aliasMap.addDoc({ docType: 'directive', id: 'MyClass', aliases: ['MyClass'], path: 'a/b/myclass' }); () => {
const doc = { docType: 'test-doc', renderedContent: '<code>MyClass</code>' }; aliasMap.addDoc(
processor.$process([doc]); {docType: 'directive', id: 'MyClass', aliases: ['MyClass'], path: 'a/b/myclass'});
expect(doc.renderedContent).toEqual('<code>MyClass</code>'); const doc = {docType: 'test-doc', renderedContent: '<code>MyClass</code>'};
}); processor.$process([doc]);
expect(doc.renderedContent).toEqual('<code>MyClass</code>');
});
it('should ignore code items that match an API doc but are attached to other text via a dash', () => { it('should ignore code items that match an API doc but are attached to other text via a dash',
aliasMap.addDoc({ docType: 'class', id: 'MyClass', aliases: ['MyClass'], path: 'a/b/myclass' }); () => {
const doc = { docType: 'test-doc', renderedContent: '<code>xyz-MyClass</code>' }; aliasMap.addDoc(
processor.$process([doc]); {docType: 'class', id: 'MyClass', aliases: ['MyClass'], path: 'a/b/myclass'});
expect(doc.renderedContent).toEqual('<code>xyz-MyClass</code>'); const doc = {docType: 'test-doc', renderedContent: '<code>xyz-MyClass</code>'};
}); processor.$process([doc]);
expect(doc.renderedContent).toEqual('<code>xyz-MyClass</code>');
});
it('should ignore code items that are filtered out by custom filters', () => { it('should ignore code items that are filtered out by custom filters', () => {
autoLinkCode.customFilters = [filterPipes]; autoLinkCode.customFilters = [filterPipes];
aliasMap.addDoc({ docType: 'pipe', id: 'MyClass', aliases: ['MyClass', 'myClass'], path: 'a/b/myclass', pipeOptions: { name: '\'myClass\'' } }); aliasMap.addDoc({
const doc = { docType: 'test-doc', renderedContent: '<code>{ xyz | myClass } { xyz|myClass } MyClass myClass OtherClass|MyClass</code>' }; docType: 'pipe',
id: 'MyClass',
aliases: ['MyClass', 'myClass'],
path: 'a/b/myclass',
pipeOptions: {name: '\'myClass\''}
});
const doc = {
docType: 'test-doc',
renderedContent:
'<code>{ xyz | myClass } { xyz|myClass } MyClass myClass OtherClass|MyClass</code>'
};
processor.$process([doc]); processor.$process([doc]);
expect(doc.renderedContent).toEqual('<code>' + expect(doc.renderedContent)
'{ xyz | <a href="a/b/myclass" class="code-anchor">myClass</a> } ' + .toEqual(
'{ xyz|<a href="a/b/myclass" class="code-anchor">myClass</a> } ' + '<code>' +
'<a href="a/b/myclass" class="code-anchor">MyClass</a> ' + '{ xyz | <a href="a/b/myclass" class="code-anchor">myClass</a> } ' +
'myClass OtherClass|<a href="a/b/myclass" class="code-anchor">MyClass</a>' + '{ xyz|<a href="a/b/myclass" class="code-anchor">myClass</a> } ' +
'</code>'); '<a href="a/b/myclass" class="code-anchor">MyClass</a> ' +
'myClass OtherClass|<a href="a/b/myclass" class="code-anchor">MyClass</a>' +
'</code>');
}); });
it('should ignore code items that match an internal API doc', () => { it('should ignore code items that match an internal API doc', () => {
aliasMap.addDoc({ docType: 'class', id: 'MyClass', aliases: ['MyClass'], path: 'a/b/myclass', internal: true }); aliasMap.addDoc({
const doc = { docType: 'test-doc', renderedContent: '<code>MyClass</code>' }; docType: 'class',
id: 'MyClass',
aliases: ['MyClass'],
path: 'a/b/myclass',
internal: true
});
const doc = {docType: 'test-doc', renderedContent: '<code>MyClass</code>'};
processor.$process([doc]); processor.$process([doc]);
expect(doc.renderedContent).toEqual('<code>MyClass</code>'); expect(doc.renderedContent).toEqual('<code>MyClass</code>');
}); });
it('should insert anchors for individual text nodes within a code block', () => { it('should insert anchors for individual text nodes within a code block', () => {
aliasMap.addDoc({ docType: 'class', id: 'MyClass', aliases: ['MyClass'], path: 'a/b/myclass' }); aliasMap.addDoc({docType: 'class', id: 'MyClass', aliases: ['MyClass'], path: 'a/b/myclass'});
const doc = { docType: 'test-doc', renderedContent: '<code><span>MyClass</span><span>MyClass</span></code>' }; const doc = {
docType: 'test-doc',
renderedContent: '<code><span>MyClass</span><span>MyClass</span></code>'
};
processor.$process([doc]); processor.$process([doc]);
expect(doc.renderedContent).toEqual('<code><span><a href="a/b/myclass" class="code-anchor">MyClass</a></span><span><a href="a/b/myclass" class="code-anchor">MyClass</a></span></code>'); expect(doc.renderedContent)
.toEqual(
'<code><span><a href="a/b/myclass" class="code-anchor">MyClass</a></span><span><a href="a/b/myclass" class="code-anchor">MyClass</a></span></code>');
}); });
it('should insert anchors for words that match within text nodes in a code block', () => { it('should insert anchors for words that match within text nodes in a code block', () => {
aliasMap.addDoc({ docType: 'class', id: 'MyClass', aliases: ['MyClass'], path: 'a/b/myclass' }); aliasMap.addDoc({docType: 'class', id: 'MyClass', aliases: ['MyClass'], path: 'a/b/myclass'});
aliasMap.addDoc({ docType: 'function', id: 'myFunc', aliases: ['myFunc'], path: 'ng/myfunc' }); aliasMap.addDoc({docType: 'function', id: 'myFunc', aliases: ['myFunc'], path: 'ng/myfunc'});
aliasMap.addDoc({ docType: 'const', id: 'MY_CONST', aliases: ['MY_CONST'], path: 'ng/my_const' }); aliasMap.addDoc({docType: 'const', id: 'MY_CONST', aliases: ['MY_CONST'], path: 'ng/my_const'});
const doc = { docType: 'test-doc', renderedContent: '<code>myFunc() {\n return new MyClass(MY_CONST);\n}</code>' }; const doc = {
docType: 'test-doc',
renderedContent: '<code>myFunc() {\n return new MyClass(MY_CONST);\n}</code>'
};
processor.$process([doc]); processor.$process([doc]);
expect(doc.renderedContent).toEqual('<code><a href="ng/myfunc" class="code-anchor">myFunc</a>() {\n return new <a href="a/b/myclass" class="code-anchor">MyClass</a>(<a href="ng/my_const" class="code-anchor">MY_CONST</a>);\n}</code>'); expect(doc.renderedContent)
.toEqual(
'<code><a href="ng/myfunc" class="code-anchor">myFunc</a>() {\n return new <a href="a/b/myclass" class="code-anchor">MyClass</a>(<a href="ng/my_const" class="code-anchor">MY_CONST</a>);\n}</code>');
}); });
it('should work with custom elements', () => { it('should work with custom elements', () => {
autoLinkCode.codeElements = ['code-example']; autoLinkCode.codeElements = ['code-example'];
aliasMap.addDoc({ docType: 'class', id: 'MyClass', aliases: ['MyClass'], path: 'a/b/myclass' }); aliasMap.addDoc({docType: 'class', id: 'MyClass', aliases: ['MyClass'], path: 'a/b/myclass'});
const doc = { docType: 'test-doc', renderedContent: '<code-example>MyClass</code-example>' }; const doc = {docType: 'test-doc', renderedContent: '<code-example>MyClass</code-example>'};
processor.$process([doc]); processor.$process([doc]);
expect(doc.renderedContent).toEqual('<code-example><a href="a/b/myclass" class="code-anchor">MyClass</a></code-example>'); expect(doc.renderedContent)
.toEqual(
'<code-example><a href="a/b/myclass" class="code-anchor">MyClass</a></code-example>');
}); });
it('should ignore code blocks that are marked with a `no-auto-link` class', () => { it('should ignore code blocks that are marked with a `no-auto-link` class', () => {
aliasMap.addDoc({ docType: 'class', id: 'MyClass', aliases: ['MyClass'], path: 'a/b/myclass' }); aliasMap.addDoc({docType: 'class', id: 'MyClass', aliases: ['MyClass'], path: 'a/b/myclass'});
const doc = { docType: 'test-doc', renderedContent: '<code class="no-auto-link">MyClass</code>' }; const doc = {docType: 'test-doc', renderedContent: '<code class="no-auto-link">MyClass</code>'};
processor.$process([doc]); processor.$process([doc]);
expect(doc.renderedContent).toEqual('<code class="no-auto-link">MyClass</code>'); expect(doc.renderedContent).toEqual('<code class="no-auto-link">MyClass</code>');
}); });