WIP: mid cherry-pick

packages/lit-dev-tools-cjs/src/api-docs/configs/lit-2.ts

@@ -15,6 +15,9 @@ const gitDir = pathlib.join(workDir, 'repo');
 const litDir = pathlib.join(gitDir, 'packages', 'lit');
 const srcDir = pathlib.join(litDir, 'src');
 
+const contextDir = pathlib.join(gitDir, 'packages', 'labs', 'context');
+const contextSrcDir = pathlib.join(contextDir, 'src');
+
 /**
  * lit.dev API docs configuration for Lit 2.x
  */
@@ -23,47 +26,36 @@ export const lit2Config: ApiDocsConfig = {
   commit: 'df67769d3b7c5b699d8c1dc57e15c3e91fe296c6',
   workDir,
   gitDir,
-  tsConfigPath: pathlib.join(litDir, 'tsconfig.json'),
   pagesOutPath: pathlib.resolve(workDir, 'pages.json'),
   symbolsOutPath: pathlib.resolve(workDir, 'symbols.json'),
   typedocRoot: pathlib.join(root, 'packages'),
 
-  extraSetupCommands: [
+  packages: [
     {
-      cmd: 'npx',
-      // Only install lit and its dependencies, so that we don't waste time
-      // installing dependencies for packages we don't generate API docs for
-      // (like tests).
-      args: ['lerna', 'bootstrap', '--scope', 'lit', '--include-dependencies'],
+      tsConfigPath: pathlib.join(litDir, 'tsconfig.json'),
+      entrypointModules: [
+        pathlib.join(srcDir, 'async-directive.ts'),
+        pathlib.join(srcDir, 'decorators.ts'),
+        pathlib.join(srcDir, 'directives/*'), // Entire directory
+        pathlib.join(srcDir, 'directive.ts'),
+        pathlib.join(srcDir, 'directive-helpers.ts'),
+        // Don't include html.ts because it is already re-exported by index.ts.
+        //   pathlib.join(srcDir, 'html.ts'),
+        // Don't include hydration because it's not ready yet.
+        //   pathlib.join(srcDir, 'hydrate.ts'),
+        //   pathlib.join(srcDir, 'hydrate-support.ts'),
+        pathlib.join(srcDir, 'index.ts'),
+        // Don't include polyfill-support.ts because it doesn't export anything.
+        //   pathlib.join(srcDir, 'polyfill-support.ts'),
+        pathlib.join(srcDir, 'static-html.ts'),
+      ]
     },
     {
-      cmd: 'npx',
-      args: [
-        'lerna',
-        'run',
-        'build:ts',
-        '--scope',
-        'lit',
-        '--include-dependencies',
-      ],
-    },
-  ],
-
-  entrypointModules: [
-    pathlib.join(srcDir, 'async-directive.ts'),
-    pathlib.join(srcDir, 'decorators.ts'),
-    pathlib.join(srcDir, 'directives/*'), // Entire directory
-    pathlib.join(srcDir, 'directive.ts'),
-    pathlib.join(srcDir, 'directive-helpers.ts'),
-    // Don't include html.ts because it is already re-exported by index.ts.
-    //   pathlib.join(srcDir, 'html.ts'),
-    // Don't include hydration because it's not ready yet.
-    //   pathlib.join(srcDir, 'hydrate.ts'),
-    //   pathlib.join(srcDir, 'hydrate-support.ts'),
-    pathlib.join(srcDir, 'index.ts'),
-    // Don't include polyfill-support.ts because it doesn't export anything.
-    //   pathlib.join(srcDir, 'polyfill-support.ts'),
-    pathlib.join(srcDir, 'static-html.ts'),
+      tsConfigPath: pathlib.join(contextDir, 'tsconfig.json'),
+      entrypointModules: [
+        pathlib.join(contextSrcDir, 'index.ts'),
+      ]
+    }
   ],
 
   symbolOrder: ['LitElement', 'ReactiveElement'],
@@ -133,6 +125,13 @@ export const lit2Config: ApiDocsConfig = {
         v1: 'api/lit-element/LitElement/',
       },
     },
+    {
+      slug: 'context',
+      title: 'Context',
+      versionLinks: {
+        v1: 'api/lit-element/LitElement/',
+      },
+    },
     {
       slug: 'misc',
       title: 'Misc',
@@ -144,6 +143,11 @@ export const lit2Config: ApiDocsConfig = {
 
   pageForSymbol(node): string {
     const entrypoint = node.entrypointSources?.[0]?.fileName ?? '';
+
+    if (entrypoint.includes('/context/')) {
+      return 'context';
+    }
+
     if (entrypoint.includes('/directives/')) {
       return 'directives';
     }

packages/lit-dev-tools-cjs/src/api-docs/configs/lit-element-2.ts

@@ -22,15 +22,19 @@ export const litElement2Config: ApiDocsConfig = {
   commit: 'c9b40e6b26dd7a9361e32421a4343949d242e0ca',
   workDir,
   gitDir,
-  tsConfigPath: pathlib.join(gitDir, 'tsconfig.json'),
   pagesOutPath: pathlib.join(workDir, 'pages.json'),
   symbolsOutPath: pathlib.join(workDir, 'symbols.json'),
   typedocRoot: srcDir,
 
-  entrypointModules: [
-    pathlib.join(srcDir, 'lit-element.ts'),
-    pathlib.join(srcDir, 'decorators.ts'),
-    pathlib.join(srcDir, 'lib', 'updating-element.ts'),
+  packages: [
+    {
+      tsConfigPath: pathlib.join(gitDir, 'tsconfig.json'),
+      entrypointModules: [
+        pathlib.join(srcDir, 'lit-element.ts'),
+        pathlib.join(srcDir, 'decorators.ts'),
+        pathlib.join(srcDir, 'lib', 'updating-element.ts'),
+      ],
+    }
   ],
 
   symbolOrder: [],

packages/lit-dev-tools-cjs/src/api-docs/configs/lit-html-1.ts

@@ -22,27 +22,31 @@ export const litHtml1Config: ApiDocsConfig = {
   commit: '022f87d7d1f541738dfec130f3635a6962f53887',
   workDir,
   gitDir,
-  tsConfigPath: pathlib.join(gitDir, 'tsconfig.json'),
   pagesOutPath: pathlib.join(workDir, 'pages.json'),
   symbolsOutPath: pathlib.join(workDir, 'symbols.json'),
   typedocRoot: srcDir,
 
-  entrypointModules: [
-    pathlib.join(srcDir, 'lit-html.ts'),
-    pathlib.join(srcDir, 'lib', 'shady-render.ts'),
-    pathlib.join(srcDir, 'directives', 'async-append.ts'),
-    pathlib.join(srcDir, 'directives', 'async-replace.ts'),
-    pathlib.join(srcDir, 'directives', 'cache.ts'),
-    pathlib.join(srcDir, 'directives', 'class-map.ts'),
-    pathlib.join(srcDir, 'directives', 'guard.ts'),
-    pathlib.join(srcDir, 'directives', 'if-defined.ts'),
-    pathlib.join(srcDir, 'directives', 'live.ts'),
-    pathlib.join(srcDir, 'directives', 'repeat.ts'),
-    pathlib.join(srcDir, 'directives', 'style-map.ts'),
-    pathlib.join(srcDir, 'directives', 'template-content.ts'),
-    pathlib.join(srcDir, 'directives', 'unsafe-html.ts'),
-    pathlib.join(srcDir, 'directives', 'unsafe-svg.ts'),
-    pathlib.join(srcDir, 'directives', 'until.ts'),
+  packages: [
+    {
+      tsConfigPath: pathlib.join(gitDir, 'tsconfig.json'),
+      entrypointModules: [
+        pathlib.join(srcDir, 'lit-html.ts'),
+        pathlib.join(srcDir, 'lib', 'shady-render.ts'),
+        pathlib.join(srcDir, 'directives', 'async-append.ts'),
+        pathlib.join(srcDir, 'directives', 'async-replace.ts'),
+        pathlib.join(srcDir, 'directives', 'cache.ts'),
+        pathlib.join(srcDir, 'directives', 'class-map.ts'),
+        pathlib.join(srcDir, 'directives', 'guard.ts'),
+        pathlib.join(srcDir, 'directives', 'if-defined.ts'),
+        pathlib.join(srcDir, 'directives', 'live.ts'),
+        pathlib.join(srcDir, 'directives', 'repeat.ts'),
+        pathlib.join(srcDir, 'directives', 'style-map.ts'),
+        pathlib.join(srcDir, 'directives', 'template-content.ts'),
+        pathlib.join(srcDir, 'directives', 'unsafe-html.ts'),
+        pathlib.join(srcDir, 'directives', 'unsafe-svg.ts'),
+        pathlib.join(srcDir, 'directives', 'until.ts'),
+      ],
+    }
   ],
 
   symbolOrder: [],

packages/lit-dev-tools-cjs/src/api-docs/generate.ts

@@ -9,7 +9,7 @@ import * as fs from 'fs/promises';
 import * as pathlib from 'path';
 import {execFile} from 'child_process';
 import {promisify} from 'util';
-import {ApiDocsTransformer} from './transformer.js';
+import {ApiDocsTransformer, Pages, SymbolMap} from './transformer.js';
 import {lit2Config} from './configs/lit-2.js';
 import {litElement2Config} from './configs/lit-element-2.js';
 import {litHtml1Config} from './configs/lit-html-1.js';
@@ -90,34 +90,41 @@ const analyze = async (config: ApiDocsConfig) => {
   }
 
   console.log(`Analyzing ${config.gitDir}`);
-  const app = new typedoc.Application();
-  app.options.addReader(new typedoc.TSConfigReader());
-  app.bootstrap({
-    tsconfig: config.tsConfigPath,
-    entryPoints: config.entrypointModules,
-    skipErrorChecking: true,
-  });
-  const root = app.convert();
-  if (!root) {
-    throw new Error('TypeDoc.Application.convert() returned undefined');
-  }
 
-  const json = await app.serializer.projectToObject(root);
-  const transformer = new ApiDocsTransformer(json, config);
-  const {pages, symbolMap} = await transformer.transform();
+  const allPages: Pages = [];
+  const allSymbols: SymbolMap = {};
+
+  for (const pkg of config.packages) {
+    const app = new typedoc.Application();
+    app.options.addReader(new typedoc.TSConfigReader());
+    app.bootstrap({
+      tsconfig: pkg.tsConfigPath,
+      entryPoints: pkg.entrypointModules,
+      skipErrorChecking: true,
+    });
+    const root = app.convert();
+    if (!root) {
+      throw new Error('TypeDoc.Application.convert() returned undefined');
+    }
+    const json = await app.serializer.projectToObject(root);
+    const transformer = new ApiDocsTransformer(json, config);
+    const {pages, symbolMap} = await transformer.transform();
+    allPages.push(...pages);
+    Object.assign(allSymbols, symbolMap);
+  }
 
   await fs.mkdir(pathlib.dirname(config.pagesOutPath), {recursive: true});
   await fs.writeFile(
     config.pagesOutPath,
-    JSON.stringify(pages, null, 2),
+    JSON.stringify(allPages, null, 2),
     'utf8'
   );
   console.log(`Wrote ${config.pagesOutPath}`);
 
   await fs.mkdir(pathlib.dirname(config.symbolsOutPath), {recursive: true});
   await fs.writeFile(
     config.symbolsOutPath,
-    JSON.stringify(symbolMap, null, 2),
+    JSON.stringify(allSymbols, null, 2),
     'utf8'
   );
   console.log(`Wrote ${config.symbolsOutPath}`);

packages/lit-dev-tools-cjs/src/api-docs/transformer.ts

@@ -62,7 +62,7 @@ const symbolToExternalLink = new Map([
  * Data consumed by lit.dev API docs Eleventy template. Each item is a separate
  * page.
  */
-type Pages = Array<{
+export type Pages = Array<{
   slug: string;
   title: string;
   items: Array<DeclarationReflection>;
@@ -72,7 +72,7 @@ type Pages = Array<{
  * Map from $symbol to the location it appears in our docs. If there is more
  * than one item, then the symbol is ambiguous.
  */
-type SymbolMap = {
+export type SymbolMap = {
   [symbol: string]: Array<Location>;
 };
 

packages/lit-dev-tools-cjs/src/api-docs/types.ts

@@ -44,6 +44,28 @@ export interface ExternalLocation {
   url: string;
 }
 
+
+export interface Package {
+  /**
+   * Path to the tsconfig.json that owns the entrypoint modules.
+   */
+  tsConfigPath: string;
+
+  /**
+   * Entrypoint TypeScript modules for TypeDoc to analyze.
+   *
+   * The modules listed here should be the preferred modules that users should
+   * import from, because import statements will be generated using these
+   * entrypoints as the module specifier (e.g. `import {LitElement} from
+   * 'lit'`). GitHub source links will be generated pointing at the ultimate
+   * location where the symbol is concretely defined (e.g.
+   * `packages/lit-element/src/lit-element.ts`).
+   *
+   * If a directory, all .ts files within it are included.
+   */
+  entrypointModules: Array<string>;
+}
+
 export interface ApiDocsConfig {
   /**
    * Git repo remote URL.
@@ -65,11 +87,6 @@ export interface ApiDocsConfig {
    */
   gitDir: string;
 
-  /**
-   * Path to the tsconfig.json that owns the entrypoint modules.
-   */
-  tsConfigPath: string;
-
   /**
    * The directory that TypeDoc chooses as the root of this package. Unclear why
    * this is unpredictable.
@@ -83,18 +100,9 @@ export interface ApiDocsConfig {
   extraSetupCommands?: Array<{cmd: string; args: string[]}>;
 
   /**
-   * Entrypoint TypeScript modules for TypeDoc to analyze.
-   *
-   * The modules listed here should be the preferred modules that users should
-   * import from, because import statements will be generated using these
-   * entrypoints as the module specifier (e.g. `import {LitElement} from
-   * 'lit'`). GitHub source links will be generated pointing at the ultimate
-   * location where the symbol is concretely defined (e.g.
-   * `packages/lit-element/src/lit-element.ts`).
-   *
-   * If a directory, all .ts files within it are included.
+   * The packages that are included in these API doc pages.
    */
-  entrypointModules: string[];
+  packages: Array<Package>;
 
   /**
    * Where to write the API data that is consumed by our Eleventy template.