build: basic command wiki documentation tool

Author: clydin

package.json

@@ -11,6 +11,7 @@
   "scripts": {
     "crazy2e": "echo This is crazy! Youre INSANE; npm run test:e2e -- --noproject ''; npm run test:e2e -- --nb-shards=4 --shard=0 --nobuild --nolink & npm run test:e2e -- --nb-shards=4 --shard=1  --nobuild --nolink & npm run test:e2e -- --nb-shards=4 --shard=2  --nobuild --nolink & npm run test:e2e -- --nb-shards=4 --shard=3 --nobuild --nolink & wait",
     "build": "node scripts/run-tool.js publish build",
+    "docs": "node scripts/run-tool.js publish docs",
     "test": "npm-run-all -c test:packages test:cli test:deps test:licenses test:messages",
     "e2e": "npm run test:e2e",
     "e2e:nightly": "node tests/run_e2e.js --nightly",

tools/publish/src/generate-docs.ts

@@ -0,0 +1,83 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import { logging, tags } from '@angular-devkit/core';
+
+export default async function () {
+  const commandsPath = __dirname + '/../../../packages/@angular/cli/commands';
+  const commandFiles = fs.readdirSync(commandsPath);
+
+  for (const commandFile of commandFiles) {
+    const commandConstructor = require(path.join(commandsPath, commandFile)).default;
+    const command = new commandConstructor(undefined, new logging.NullLogger());
+
+    if (command.hidden) {
+      continue;
+    }
+
+    try {
+      await command.initialize({});
+    } catch {
+      console.log('initialize failed: ' + commandFile);
+    }
+
+    let optionText;
+    if (!command.options) {
+      optionText = '';
+    } else {
+      optionText = (command.options as any[])
+        .filter(option => !option.hidden)
+        .map(option => {
+          let defaultText = '';
+          if (option.default) {
+            defaultText = `<em>default value: ${option.default}</em>`;
+          }
+          let aliasText = '';
+          if (option.aliases && option.aliases.length > 0) {
+            aliasText = (option.aliases as string[])
+              .map(alias => '<code>' + (alias.length === 1 ? '-' : '--') + alias + '</code>')
+              .join(',');
+            aliasText = ` (aliases: ${aliasText})`;
+          }
+
+          return tags.stripIndent`
+            <details>
+              <summary>${option.name}</summary>
+              <p>
+                <code>--${option.name}</code>${aliasText} ${defaultText}
+              </p>
+              <p>
+                ${option.description}
+              </p>
+            </details>
+          `;
+        }).join('\n');
+    }
+
+    const docFile = path.join(
+      __dirname,
+      '../../../docs/documentation/',
+      path.basename(commandFile, '.ts') + '.md');
+
+    let docText;
+    if (fs.existsSync(docFile)) {
+      docText = fs.readFileSync(docFile, 'utf8');
+      docText = docText.slice(0, docText.indexOf('## Options') + 10);
+    } else {
+      // tslint:disable:max-line-length
+      docText = tags.stripIndent`
+        <!-- Links in /docs/documentation should NOT have \`.md\` at the end, because they end up in our wiki at release. -->
+
+        # ng ${command.name}
+
+        ## Overview
+        ${command.description}
+
+        ## Options
+      `;
+      // tslint:enable:max-line-length
+    }
+
+    const finalText = docText + '\n' + (optionText ? optionText : 'None.') + '\n';
+    fs.writeFileSync(docFile, finalText);
+  }
+}

tools/publish/src/main.ts

@@ -43,6 +43,7 @@ switch (command) {
   case 'build-schema': commandFn = require('./build-schema').default; break;
   case 'update-version': commandFn = require('./update-version').default; break;
   case 'changelog': commandFn = require('./changelog').default; break;
+  case 'docs': commandFn = require('./generate-docs').default; break;
 }
 
 if (commandFn) {