build(aio): improve accuracy of code auto-linking (#22494)
The new version of `dgeni-packages/typescript` no longer strips out "namespaces" from types, which was part of the problem of not autolinking correctly to `HttpEventType.Response`. Another part of the problem was that we did not include `.` characters when matching potential code blocks for auto-linking, which precluded properties of enums from being linked. Finally, members we not being given a `path` property, which is needed to effectively autolink to them. This is now set in the `simplifyMemberAnchors` processor. Closes #21375 PR Close #22494
This commit is contained in:
parent
997b30a093
commit
0e311e3918
|
@ -107,7 +107,7 @@
|
|||
"cross-spawn": "^5.1.0",
|
||||
"css-selector-parser": "^1.3.0",
|
||||
"dgeni": "^0.4.7",
|
||||
"dgeni-packages": "^0.24.3",
|
||||
"dgeni-packages": "^0.25.0",
|
||||
"entities": "^1.1.1",
|
||||
"eslint": "^3.19.0",
|
||||
"eslint-plugin-jasmine": "^2.2.0",
|
||||
|
|
|
@ -130,6 +130,6 @@ module.exports = new Package('angular-api', [basePackage, typeScriptPackage])
|
|||
]);
|
||||
convertToJsonProcessor.docTypes = convertToJsonProcessor.docTypes.concat(DOCS_TO_CONVERT);
|
||||
postProcessHtml.docTypes = convertToJsonProcessor.docTypes.concat(DOCS_TO_CONVERT);
|
||||
autoLinkCode.docTypes = DOCS_TO_CONVERT;
|
||||
autoLinkCode.docTypes = DOCS_TO_CONVERT.concat(['member']);
|
||||
autoLinkCode.codeElements = ['code', 'code-example', 'code-pane'];
|
||||
});
|
||||
|
|
|
@ -5,15 +5,21 @@
|
|||
*/
|
||||
module.exports = function simplifyMemberAnchors() {
|
||||
return {
|
||||
$runAfter: ['extra-docs-added'],
|
||||
$runBefore: ['computing-paths'],
|
||||
$runAfter: ['paths-computed'],
|
||||
$runBefore: ['rendering-docs'],
|
||||
$process: function(docs) {
|
||||
return docs.forEach(doc => {
|
||||
if (doc.members) {
|
||||
doc.members.forEach(member => member.anchor = computeAnchor(member));
|
||||
doc.members.forEach(member => {
|
||||
member.anchor = computeAnchor(member);
|
||||
member.path = doc.path + '#' + member.anchor;
|
||||
});
|
||||
}
|
||||
if (doc.statics) {
|
||||
doc.statics.forEach(member => member.anchor = computeAnchor(member));
|
||||
doc.statics.forEach(member => {
|
||||
member.anchor = computeAnchor(member);
|
||||
member.path = doc.path + '#' + member.anchor;
|
||||
});
|
||||
}
|
||||
});
|
||||
}
|
||||
|
|
|
@ -0,0 +1,72 @@
|
|||
const testPackage = require('../../helpers/test-package');
|
||||
const processorFactory = require('./simplifyMemberAnchors');
|
||||
const Dgeni = require('dgeni');
|
||||
|
||||
describe('simplifyMemberAnchors processor', () => {
|
||||
|
||||
it('should be available on the injector', () => {
|
||||
const dgeni = new Dgeni([testPackage('angular-api-package')]);
|
||||
const injector = dgeni.configureInjector();
|
||||
const processor = injector.get('simplifyMemberAnchors');
|
||||
expect(processor.$process).toBeDefined();
|
||||
expect(processor.$runAfter).toEqual(['paths-computed']);
|
||||
expect(processor.$runBefore).toEqual(['rendering-docs']);
|
||||
});
|
||||
|
||||
describe('$process', () => {
|
||||
describe('docs without members', () => {
|
||||
it('should ignore the docs', () => {
|
||||
const processor = processorFactory();
|
||||
const docs = [
|
||||
{ id: 'some-doc' },
|
||||
{ id: 'some-other' }
|
||||
];
|
||||
processor.$process(docs);
|
||||
expect(docs).toEqual([
|
||||
{ id: 'some-doc' },
|
||||
{ id: 'some-other' }
|
||||
]);
|
||||
});
|
||||
});
|
||||
|
||||
describe('docs with members', () => {
|
||||
it('should compute an anchor for each instance member', () => {
|
||||
const processor = processorFactory();
|
||||
const docs = [
|
||||
{ id: 'some-doc', members: [ { name: 'foo' }, { name: 'new' }, { name: '' } ] }
|
||||
];
|
||||
processor.$process(docs);
|
||||
expect(docs[0].members.map(member => member.anchor)).toEqual(['foo', 'new', 'call']);
|
||||
});
|
||||
|
||||
it('should compute a path for each instance member', () => {
|
||||
const processor = processorFactory();
|
||||
const docs = [
|
||||
{ id: 'some-doc', path: 'a/b/c', members: [ { name: 'foo' }, { name: 'new' }, { name: '' } ] }
|
||||
];
|
||||
processor.$process(docs);
|
||||
expect(docs[0].members.map(member => member.path)).toEqual(['a/b/c#foo', 'a/b/c#new', 'a/b/c#call']);
|
||||
});
|
||||
});
|
||||
|
||||
describe('docs with static members', () => {
|
||||
it('should compute an anchor for each static member', () => {
|
||||
const processor = processorFactory();
|
||||
const docs = [
|
||||
{ id: 'some-doc', statics: [ { name: 'foo' }, { name: 'new' }, { name: '' } ] }
|
||||
];
|
||||
processor.$process(docs);
|
||||
expect(docs[0].statics.map(member => member.anchor)).toEqual(['foo', 'new', 'call']);
|
||||
});
|
||||
|
||||
it('should compute a path for each static member', () => {
|
||||
const processor = processorFactory();
|
||||
const docs = [
|
||||
{ id: 'some-doc', path: 'a/b/c', statics: [ { name: 'foo' }, { name: 'new' }, { name: '' } ] }
|
||||
];
|
||||
processor.$process(docs);
|
||||
expect(docs[0].statics.map(member => member.path)).toEqual(['a/b/c#foo', 'a/b/c#new', 'a/b/c#call']);
|
||||
});
|
||||
});
|
||||
});
|
||||
});
|
|
@ -45,7 +45,7 @@ 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_-]+)/)
|
||||
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
|
||||
|
|
|
@ -9,7 +9,7 @@ describe('autoLinkCode post-processor', () => {
|
|||
const dgeni = new Dgeni([testPackage]);
|
||||
const injector = dgeni.configureInjector();
|
||||
autoLinkCode = injector.get('autoLinkCode');
|
||||
autoLinkCode.docTypes = ['class', 'pipe', 'function', 'const'];
|
||||
autoLinkCode.docTypes = ['class', 'pipe', 'function', 'const', 'member'];
|
||||
aliasMap = injector.get('aliasMap');
|
||||
processor = injector.get('postProcessHtml');
|
||||
processor.docTypes = ['test-doc'];
|
||||
|
@ -31,6 +31,13 @@ describe('autoLinkCode post-processor', () => {
|
|||
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', () => {
|
||||
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>' };
|
||||
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', () => {
|
||||
aliasMap.addDoc({ docType: 'guide', id: 'MyClass', aliases: ['MyClass'], path: 'a/b/myclass' });
|
||||
const doc = { docType: 'test-doc', renderedContent: '<code>MyClass</code>' };
|
||||
|
|
|
@ -2312,9 +2312,9 @@ devtools-timeline-model@1.1.6:
|
|||
chrome-devtools-frontend "1.0.401423"
|
||||
resolve "1.1.7"
|
||||
|
||||
dgeni-packages@^0.24.3:
|
||||
version "0.24.3"
|
||||
resolved "https://registry.yarnpkg.com/dgeni-packages/-/dgeni-packages-0.24.3.tgz#153ce2bf9d71a70cd8c71171c7f49adf0d725ab9"
|
||||
dgeni-packages@^0.25.0:
|
||||
version "0.25.0"
|
||||
resolved "https://registry.yarnpkg.com/dgeni-packages/-/dgeni-packages-0.25.0.tgz#380f0b569ae36d82959252604b729e85e0cd7d4a"
|
||||
dependencies:
|
||||
canonical-path "0.0.2"
|
||||
catharsis "^0.8.1"
|
||||
|
|
Loading…
Reference in New Issue