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

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

Browse Source 
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
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 = [];