add doc generator

tools/workspace-plugin/generators.json

@@ -9,6 +9,11 @@
       "factory": "./src/generators/make-schemas/generator",
       "schema": "./src/generators/make-schemas/schema.json",
       "description": "make-schemas generator"
+    },
+    "doc": {
+      "factory": "./src/generators/doc/generator",
+      "schema": "./src/generators/doc/schema.json",
+      "description": "Generate documentation  for packages"
     }
   }
 }

tools/workspace-plugin/package.json

@@ -2,5 +2,8 @@
   "name": "@gb-nx/workspace-plugin",
   "version": "0.0.1",
   "type": "commonjs",
-  "generators": "./generators.json"
+  "generators": "./generators.json",
+  "dependencies": {
+    "@nx/devkit": "17.2.7"
+  }
 }

tools/workspace-plugin/src/generators/doc/generator.spec.ts

@@ -0,0 +1,18 @@
+import { type Tree } from '@nx/devkit';
+import { createTreeWithEmptyWorkspace } from '@nx/devkit/testing';
+import { docGenerator } from './generator';
+import { type DocGeneratorSchema } from './schema';
+
+describe('doc generator', () => {
+  let tree: Tree;
+
+  beforeEach(() => {
+    tree = createTreeWithEmptyWorkspace();
+  });
+
+  it('should run successfully', async () => {
+    await docGenerator(tree, {});
+    // const config = readProjectConfiguration(tree, 'test');
+    expect(2 + 2).not.toEqual(5);
+  });
+});

tools/workspace-plugin/src/generators/doc/generator.ts

@@ -0,0 +1,69 @@
+import {
+  formatFiles,
+  getProjects,
+  joinPathFragments,
+  readJson,
+  type GeneratorsJson,
+  type Tree,
+} from '@nx/devkit';
+import { type JSONSchema } from 'json-schema-to-typescript';
+import { type PackageJson } from 'nx/src/utils/package-json';
+import { Document, h1, h2, h3, table } from '../../markdown';
+import { type DocGeneratorSchema } from './schema';
+
+export async function docGenerator(
+  tree: Tree,
+  _options: DocGeneratorSchema
+): Promise<void> {
+  for (const [, b] of getProjects(tree)) {
+    const pj = joinPathFragments(b.root, 'package.json');
+    if (tree.exists(pj)) {
+      const pkg = readJson<PackageJson>(tree, pj);
+      const lines = [
+        h1(pkg.name),
+        '',
+        `See \`nx list ${pkg.name}\` for more information.`,
+        '',
+      ];
+      if (pkg.generators) {
+        const generatorsf = joinPathFragments(b.root, pkg.generators);
+        if (tree.exists(generatorsf)) {
+          lines.push(h2('Generators'));
+          const jgens = readJson<GeneratorsJson>(tree, generatorsf);
+
+          for (const [gn, generator] of Object.entries(
+            jgens.generators ?? {}
+          )) {
+            const tbody: [string, string, string][] = [];
+            const schm = readJson<JSONSchema>(
+              tree,
+              joinPathFragments(b.root, generator.schema)
+            );
+            if (schm.properties) {
+              for (const [n, prop] of Object.entries(schm.properties)) {
+                if (typeof prop.type === 'string') {
+                  tbody.push([`${n}`, prop.type, prop.description ?? '']);
+                }
+              }
+              lines.push(
+                h3(gn),
+                schm.title ?? '',
+                '',
+                generator.description ?? '',
+                '',
+                ...table(['Option', 'Type', 'Description'], tbody)
+              );
+            }
+          }
+        }
+      }
+      tree.write(
+        joinPathFragments(b.root, 'commands.md'),
+        new Document(lines).print().join('\n')
+      );
+    }
+  }
+  await formatFiles(tree);
+}
+
+export default docGenerator;

tools/workspace-plugin/src/generators/doc/schema.d.ts

@@ -0,0 +1,3 @@
+export interface DocGeneratorSchema {
+  exclude?: string[];
+}

tools/workspace-plugin/src/generators/doc/schema.json

@@ -0,0 +1,27 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Create markdown documents for a plugin workspace",
+  "description": "Create a document detailing options for plugin projects",
+  "examples": [
+    {
+      "command": "nx g doc",
+      "description": "Create a document listing every project"
+    },
+    {
+      "command": "nx g doc --exclude=my-app --exclude=other-plugin",
+      "description": "Create a document listing every project except my-app and other-plugin"
+    }
+  ],
+  "type": "object",
+  "properties": {
+    "exclude": {
+      "type": "array",
+      "description": "Projects to exclude",
+      "items": {
+        "type": "string"
+      }
+    }
+  },
+  "additionalProperties": false,
+  "required": []
+}