From 526537fefe176e8336e6515e353ed57d18c64db9 Mon Sep 17 00:00:00 2001 From: Pete Bacon Darwin Date: Sat, 16 Nov 2019 22:18:34 +0000 Subject: [PATCH] style(docs-infra): reformat the auto-link-code files (#33877) PR Close #33877 --- .../post-processors/auto-link-code.js | 41 ++--- .../post-processors/auto-link-code.spec.js | 154 ++++++++++++------ 2 files changed, 125 insertions(+), 70 deletions(-) diff --git a/aio/tools/transforms/angular-base-package/post-processors/auto-link-code.js b/aio/tools/transforms/angular-base-package/post-processors/auto-link-code.js index 2f562cccf0..589af005bf 100644 --- a/aio/tools/transforms/angular-base-package/post-processors/auto-link-code.js +++ b/aio/tools/transforms/angular-base-package/post-processors/auto-link-code.js @@ -26,18 +26,17 @@ module.exports = function autoLinkCode(getDocFromAlias) { autoLinkCodeImpl.codeElements = ['code']; return autoLinkCodeImpl; - function autoLinkCodeImpl() { + function autoLinkCodeImpl() { return (ast) => { visit(ast, 'element', (node, ancestors) => { // Only interested in code elements that are not inside links - if (autoLinkCodeImpl.codeElements.some(elementType => - is(node, elementType)) && - (!node.properties.className || node.properties.className.indexOf('no-auto-link') === -1) && + if (autoLinkCodeImpl.codeElements.some(elementType => is(node, elementType)) && + (!node.properties.className || + node.properties.className.indexOf('no-auto-link') === -1) && ancestors.every(ancestor => !is(ancestor, 'a'))) { visit(node, 'text', (node, ancestors) => { // Only interested in text nodes that are not inside links if (ancestors.every(ancestor => !is(ancestor, 'a'))) { - const parent = ancestors[ancestors.length - 1]; 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)); } else { // Parse the text for words that we can convert to links - const nodes = textContent(node).split(/([A-Za-z0-9_.-]+)/) - .filter(word => word.length) - .map((word, index, words) => { - // remove docs that fail the custom filter tests - const filteredDocs = autoLinkCodeImpl.customFilters.reduce((docs, filter) => filter(docs, words, index), getDocFromAlias(word)); - return foundValidDoc(filteredDocs) ? - createLinkNode(filteredDocs[0], word) : // Create a link wrapping the text node. - { type: 'text', value: word }; // this is just text so push a new text node - }); + const nodes = + textContent(node) + .split(/([A-Za-z0-9_.-]+)/) + .filter(word => word.length) + .map((word, index, words) => { + // remove docs that fail the custom filter tests + const filteredDocs = autoLinkCodeImpl.customFilters.reduce( + (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 Array.prototype.splice.apply(parent.children, [index, 1].concat(nodes)); @@ -68,17 +72,16 @@ module.exports = function autoLinkCode(getDocFromAlias) { } function foundValidDoc(docs) { - return docs.length === 1 && - !docs[0].internal && - autoLinkCodeImpl.docTypes.indexOf(docs[0].docType) !== -1; + return docs.length === 1 && !docs[0].internal && + autoLinkCodeImpl.docTypes.indexOf(docs[0].docType) !== -1; } function createLinkNode(doc, text) { return { type: 'element', tagName: 'a', - properties: { href: doc.path, class: 'code-anchor' }, - children: [{ type: 'text', value: text }] + properties: {href: doc.path, class: 'code-anchor'}, + children: [{type: 'text', value: text}] }; } }; diff --git a/aio/tools/transforms/angular-base-package/post-processors/auto-link-code.spec.js b/aio/tools/transforms/angular-base-package/post-processors/auto-link-code.spec.js index 414bac60fd..fa8e3a740d 100644 --- a/aio/tools/transforms/angular-base-package/post-processors/auto-link-code.spec.js +++ b/aio/tools/transforms/angular-base-package/post-processors/auto-link-code.spec.js @@ -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', () => { - aliasMap.addDoc({ docType: 'class', id: 'MyClass', aliases: ['MyClass'], path: 'a/b/myclass' }); - const doc = { docType: 'test-doc', renderedContent: 'MyClass' }; + aliasMap.addDoc({docType: 'class', id: 'MyClass', aliases: ['MyClass'], path: 'a/b/myclass'}); + const doc = {docType: 'test-doc', renderedContent: 'MyClass'}; processor.$process([doc]); - expect(doc.renderedContent).toEqual('MyClass'); + expect(doc.renderedContent) + .toEqual('MyClass'); }); 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' }); - const doc = { docType: 'test-doc', renderedContent: 'foo.MyClass' }; + aliasMap.addDoc({ + docType: 'class', + id: 'MyClass', + aliases: ['MyClass', 'foo.MyClass'], + path: 'a/b/myclass' + }); + const doc = {docType: 'test-doc', renderedContent: 'foo.MyClass'}; processor.$process([doc]); - expect(doc.renderedContent).toEqual('foo.MyClass'); + expect(doc.renderedContent) + .toEqual('foo.MyClass'); }); - 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: 'someFn(): MyEnum.Value' }; - processor.$process([doc]); - expect(doc.renderedContent).toEqual('someFn(): MyEnum.Value'); - }); + 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: 'someFn(): MyEnum.Value'}; + processor.$process([doc]); + expect(doc.renderedContent) + .toEqual( + 'someFn(): MyEnum.Value'); + }); 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' }); - const doc = { docType: 'test-doc', renderedContent: 'MyClass' }; + aliasMap.addDoc({docType: 'guide', id: 'MyClass', aliases: ['MyClass'], path: 'a/b/myclass'}); + const doc = {docType: 'test-doc', renderedContent: 'MyClass'}; processor.$process([doc]); expect(doc.renderedContent).toEqual('MyClass'); }); it('should ignore code items that are already inside a link', () => { - aliasMap.addDoc({ docType: 'class', id: 'MyClass', aliases: ['MyClass'], path: 'a/b/myclass' }); - const doc = { docType: 'test-doc', renderedContent: '
MyClass
' }; + aliasMap.addDoc({docType: 'class', id: 'MyClass', aliases: ['MyClass'], path: 'a/b/myclass'}); + const doc = { + docType: 'test-doc', + renderedContent: '
MyClass
' + }; processor.$process([doc]); expect(doc.renderedContent).toEqual('
MyClass
'); }); - 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: 'MyClass' }; - processor.$process([doc]); - expect(doc.renderedContent).toEqual('MyClass'); - }); + 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: 'MyClass'}; + processor.$process([doc]); + expect(doc.renderedContent).toEqual('MyClass'); + }); - 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: 'xyz-MyClass' }; - processor.$process([doc]); - expect(doc.renderedContent).toEqual('xyz-MyClass'); - }); + 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: 'xyz-MyClass'}; + processor.$process([doc]); + expect(doc.renderedContent).toEqual('xyz-MyClass'); + }); it('should ignore code items that are filtered out by custom filters', () => { autoLinkCode.customFilters = [filterPipes]; - aliasMap.addDoc({ docType: 'pipe', id: 'MyClass', aliases: ['MyClass', 'myClass'], path: 'a/b/myclass', pipeOptions: { name: '\'myClass\'' } }); - const doc = { docType: 'test-doc', renderedContent: '{ xyz | myClass } { xyz|myClass } MyClass myClass OtherClass|MyClass' }; + aliasMap.addDoc({ + docType: 'pipe', + id: 'MyClass', + aliases: ['MyClass', 'myClass'], + path: 'a/b/myclass', + pipeOptions: {name: '\'myClass\''} + }); + const doc = { + docType: 'test-doc', + renderedContent: + '{ xyz | myClass } { xyz|myClass } MyClass myClass OtherClass|MyClass' + }; processor.$process([doc]); - expect(doc.renderedContent).toEqual('' + - '{ xyz | myClass } ' + - '{ xyz|myClass } ' + - 'MyClass ' + - 'myClass OtherClass|MyClass' + - ''); + expect(doc.renderedContent) + .toEqual( + '' + + '{ xyz | myClass } ' + + '{ xyz|myClass } ' + + 'MyClass ' + + 'myClass OtherClass|MyClass' + + ''); }); 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 }); - const doc = { docType: 'test-doc', renderedContent: 'MyClass' }; + aliasMap.addDoc({ + docType: 'class', + id: 'MyClass', + aliases: ['MyClass'], + path: 'a/b/myclass', + internal: true + }); + const doc = {docType: 'test-doc', renderedContent: 'MyClass'}; processor.$process([doc]); expect(doc.renderedContent).toEqual('MyClass'); }); it('should insert anchors for individual text nodes within a code block', () => { - aliasMap.addDoc({ docType: 'class', id: 'MyClass', aliases: ['MyClass'], path: 'a/b/myclass' }); - const doc = { docType: 'test-doc', renderedContent: 'MyClassMyClass' }; + aliasMap.addDoc({docType: 'class', id: 'MyClass', aliases: ['MyClass'], path: 'a/b/myclass'}); + const doc = { + docType: 'test-doc', + renderedContent: 'MyClassMyClass' + }; processor.$process([doc]); - expect(doc.renderedContent).toEqual('MyClassMyClass'); + expect(doc.renderedContent) + .toEqual( + 'MyClassMyClass'); }); 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: 'function', id: 'myFunc', aliases: ['myFunc'], path: 'ng/myfunc' }); - aliasMap.addDoc({ docType: 'const', id: 'MY_CONST', aliases: ['MY_CONST'], path: 'ng/my_const' }); - const doc = { docType: 'test-doc', renderedContent: 'myFunc() {\n return new MyClass(MY_CONST);\n}' }; + 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: 'const', id: 'MY_CONST', aliases: ['MY_CONST'], path: 'ng/my_const'}); + const doc = { + docType: 'test-doc', + renderedContent: 'myFunc() {\n return new MyClass(MY_CONST);\n}' + }; processor.$process([doc]); - expect(doc.renderedContent).toEqual('myFunc() {\n return new MyClass(MY_CONST);\n}'); + expect(doc.renderedContent) + .toEqual( + 'myFunc() {\n return new MyClass(MY_CONST);\n}'); }); it('should work with custom elements', () => { autoLinkCode.codeElements = ['code-example']; - aliasMap.addDoc({ docType: 'class', id: 'MyClass', aliases: ['MyClass'], path: 'a/b/myclass' }); - const doc = { docType: 'test-doc', renderedContent: 'MyClass' }; + aliasMap.addDoc({docType: 'class', id: 'MyClass', aliases: ['MyClass'], path: 'a/b/myclass'}); + const doc = {docType: 'test-doc', renderedContent: 'MyClass'}; processor.$process([doc]); - expect(doc.renderedContent).toEqual('MyClass'); + expect(doc.renderedContent) + .toEqual( + 'MyClass'); }); 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' }); - const doc = { docType: 'test-doc', renderedContent: 'MyClass' }; + aliasMap.addDoc({docType: 'class', id: 'MyClass', aliases: ['MyClass'], path: 'a/b/myclass'}); + const doc = {docType: 'test-doc', renderedContent: 'MyClass'}; processor.$process([doc]); expect(doc.renderedContent).toEqual('MyClass'); });