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

fix(docs-infra): correctly generate CLI commands docs when the overview page moves (#38365) 

Previously, the [processCliCommands][1] dgeni processor, which is used
to generate the docs pages for the CLI commands, expected the CLI
commands overview page (with a URL of `cli`) to exist as a child of a
top-level navigation section (`CLI Commands`). If one tried to move the
`CLI Commands` section inside another section, `processCliCommnads`
would fail to find it and thus fail to generate the CLI commands docs.
This problem came up in #38353.

This commit updates the `processCliCommands` processor to be able to
find it regardless of the position of the `CLI Commands` section inside
the navigation doc.

[1]:
dca4443a8e/aio/tools/transforms/cli-docs-package/processors/processCliCommands.js (L7-L9)

PR Close #38365
This commit is contained in:
George Kalpakas 2020-08-06 19:39:06 +03:00 committed by Andrew Kushnir
parent dca4443a8e
commit 0551fbdf88
2 changed files with 85 additions and 10 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

36
aio/tools/transforms/cli-docs-package/processors/processCliCommands.js
View File

@ -4,11 +4,9 @@ module.exports = function processCliCommands(createDocMessage) {
$runBefore: ['rendering-docs'],
$process(docs) {
const navigationDoc = docs.find(doc => doc.docType === 'navigation-json');
const navigationNode = navigationDoc &&
navigationDoc.data['SideNav'].find(
node => node.children && node.children.length && node.children[0].url === 'cli');
const cliCommandsNode = navigationDoc && findCliCommandsNode(navigationDoc.data['SideNav']);
if (!navigationNode) {
if (!cliCommandsNode) {
throw new Error(createDocMessage(
'Missing `cli` url - CLI Commands must include a first child node with url set at `cli`',
navigationDoc));
@ -24,13 +22,41 @@ module.exports = function processCliCommands(createDocMessage) {
doc.optionKeywords = Array.from(optionKeywords).join(' ');
// Add to navigation doc
navigationNode.children.push({url: doc.path, title: `ng ${doc.name}`});
cliCommandsNode.children.push({url: doc.path, title: `ng ${doc.name}`});
}
});
}
};
};
// Look for the `CLI Commands` navigation node. It is the node whose first child has `url: 'cli'`.
// (NOTE: Using the URL instead of the title, because it is more robust.)
function findCliCommandsNode(nodes) {
// We will "recursively" check all navigation nodes and their children (in breadth-first order),
// until we find the `CLI Commands` node. Keep a list of nodes lists to check.
// (NOTE: Each item in the list is a LIST of nodes.)
const nodesList = [nodes];
while (nodesList.length > 0) {
// Get the first item from the list of nodes lists.
const currentNodes = nodesList.shift();
const cliCommandsNode = currentNodes.find(isCliCommandsNode);
// One of the nodes in `currentNodes` was the `CLI Commands` node. Return it.
if (cliCommandsNode) return cliCommandsNode;
// The `CLI Commands` node is not in `currentNodes`. Check each node's children (if any).
currentNodes.forEach(node => node.children && nodesList.push(node.children));
}
// We checked all navigation nodes and their children and did not find the `CLI Commands` node.
return undefined;
}
function isCliCommandsNode(node) {
return node.children && node.children.length && node.children[0].url === 'cli';
}
function processOptions(container, options, optionKeywords) {
container.positionalOptions = [];
container.namedOptions = [];

59
aio/tools/transforms/cli-docs-package/processors/processCliCommands.spec.js
View File

@ -258,14 +258,15 @@ describe('processCliCommands processor', () => {
docType: 'navigation-json',
data: {
SideNav: [
{url: 'some/page', title: 'Some Page'}, {
{url: 'some/page', title: 'Some Page'},
{
title: 'CLI Commands',
tooltip: 'Angular CLI command reference',
children: [{'title': 'Overview', 'url': 'cli'}]
children: [{'title': 'Overview', 'url': 'cli'}],
},
{url: 'other/page', title: 'Other Page'}
]
}
{url: 'other/page', title: 'Other Page'},
],
},
};
processor.$process([command, navigation]);
expect(navigation.data.SideNav[1].title).toEqual('CLI Commands');
@ -275,6 +276,54 @@ describe('processCliCommands processor', () => {
]);
});
it('should detect the CLI node if it is nested in another node (as long as there is a first child node with a `cli` url',
() => {
const command = {
docType: 'cli-command',
name: 'command1',
commandAliases: ['alias1', 'alias2'],
options: [],
path: 'cli/command1',
};
const navigation = {
docType: 'navigation-json',
data: {
SideNav: [
{url: 'some/page', title: 'Some Page'},
{
title: 'CLI Commands Grandparent',
children: [
{url: 'some/nested/page', title: 'Some Nested Page'},
{
title: 'CLI Commands Parent',
children: [
{url: 'some/more/nested/page', title: 'Some More Nested Page'},
{
title: 'CLI Commands',
tooltip: 'Angular CLI command reference',
children: [{'title': 'Overview', 'url': 'cli'}],
},
{url: 'other/more/nested/page', title: 'Other More Nested Page'},
],
},
{url: 'other/nested/page', title: 'Other Nested Page'},
],
},
{url: 'other/page', title: 'Other Page'},
],
},
};
processor.$process([command, navigation]);
const cliCommandsNode = navigation.data.SideNav[1].children[1].children[1];
expect(cliCommandsNode.title).toEqual('CLI Commands');
expect(cliCommandsNode.children).toEqual([
{url: 'cli', title: 'Overview'},
{url: 'cli/command1', title: 'ng command1'},
]);
});
it('should complain if there is no child with `cli` url', () => {
const command = {
docType: 'cli-command',