docs: bot to trigger update-docs on merge to main

.github/workflows/update-docs-on-main.yml

@@ -0,0 +1,44 @@
+name: Update API Docs
+
+on:
+  push:
+    branches: main
+  workflow_dispatch:
+    # allows triggering from the gihub UI
+jobs:
+  check-for-doc-changes:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v3
+        with:
+          node-version: 20
+          cache: npm
+      - uses: google/wireit@setup-github-actions-caching/v1
+
+      - name: Install Dependencies
+        run: npm ci
+
+      - name: Update Docs
+        run: npm run update-docs
+
+      - name: Check if update-docs produces git diff
+        id: ifChange
+        run: git diff --exit-code || echo "::set-output name=changed::yes"
+
+      - name: Create PR
+        if: steps.ifChange.outputs.changed == 'yes'
+        uses: peter-evans/create-pull-request@v5
+        with:
+          token: ${{ secrets.LIT_ROBOT_ACCESS_TOKEN }}
+          commit-message: 'docs: update API docs'
+          author: lit-robot <lit-robot@google.com>
+          committer: lit-robot <lit-robot@google.com>
+          title: 'docs: update API docs'
+          body: This PR was auto generated by the update-docs-on-main GitHub action.
+          reviewers: e111077,asyncliz,AndrewJakubowicz
+          branch: auto-update-docs
+          labels: |
+            Ready for Google
+            preview-catalog

package-lock.json

@@ -16,6 +16,7 @@
         "tslib": "^2.4.0"
       },
       "devDependencies": {
+        "@lit-labs/analyzer": "^0.9.2",
         "@types/jasmine": "^4.0.3",
         "@web/test-runner": "^0.15.0",
         "@web/test-runner-playwright": "^0.9.0",
@@ -769,6 +770,29 @@
         "@jridgewell/sourcemap-codec": "1.4.14"
       }
     },
+    "node_modules/@lit-labs/analyzer": {
+      "version": "0.9.2",
+      "resolved": "https://registry.npmjs.org/@lit-labs/analyzer/-/analyzer-0.9.2.tgz",
+      "integrity": "sha512-1jaBJWziySwoqS2ZpIcCMufgBvmyPGsCJONitqj3Z9VzKiZzErJjcp/kJv4TiWdYKQWU++K2zsEXtktQxJ4soQ==",
+      "dev": true,
+      "dependencies": {
+        "package-json-type": "^1.0.3",
+        "typescript": "~5.0.0"
+      }
+    },
+    "node_modules/@lit-labs/analyzer/node_modules/typescript": {
+      "version": "5.0.4",
+      "resolved": "https://registry.npmjs.org/typescript/-/typescript-5.0.4.tgz",
+      "integrity": "sha512-cW9T5W9xY37cc+jfEnaUvX91foxtHkza3Nw3wkoF4sSlKn0MONdkdEndig/qPBWXNkmplh3NzayQzCiHM4/hqw==",
+      "dev": true,
+      "bin": {
+        "tsc": "bin/tsc",
+        "tsserver": "bin/tsserver"
+      },
+      "engines": {
+        "node": ">=12.20"
+      }
+    },
     "node_modules/@lit-labs/eleventy-plugin-lit": {
       "version": "1.0.1",
       "resolved": "https://registry.npmjs.org/@lit-labs/eleventy-plugin-lit/-/eleventy-plugin-lit-1.0.1.tgz",
@@ -5715,6 +5739,12 @@
         "url": "https://github.com/sponsors/sindresorhus"
       }
     },
+    "node_modules/package-json-type": {
+      "version": "1.0.3",
+      "resolved": "https://registry.npmjs.org/package-json-type/-/package-json-type-1.0.3.tgz",
+      "integrity": "sha512-Bey4gdRuOwDbS8Fj1qA3/pTq5r8pqiI5E3tjSqCdhaLSsyGG364VFzXLTIexN5AaNGe/vgdBzLfoKdr7EVg2KQ==",
+      "dev": true
+    },
     "node_modules/param-case": {
       "version": "2.1.1",
       "resolved": "https://registry.npmjs.org/param-case/-/param-case-2.1.1.tgz",

package.json

@@ -113,7 +113,7 @@
       "dependencies": ["./catalog:build:prod"]
     },
     "build:analyzer": {
-      "command": "tsc -b scripts/analyzer/tsconfig.json --pretty",
+      "command": "tsc -b scripts/tsconfig.json --pretty",
       "files": [
         "scripts/tsconfig.json",
         "scripts/analyzer/**/*.ts",

scripts/analyzer/update-docs.ts

@@ -5,15 +5,13 @@
  */
 
 import {AbsolutePath, Analyzer, createPackageAnalyzer,} from '@lit-labs/analyzer/package-analyzer.js';
-import * as fs from 'fs/promises.js';
+import * as fs from 'fs/promises';
 import * as path from 'path';
 
-import {analyzeElementApi, MdModuleInfo, MdPropertyInfo,} from './analyze-element.js';
+import {analyzeElementApi, MdMethodParameterInfo, MdModuleInfo, MdPropertyInfo,} from './analyze-element.js';
 import {docsToElementMapping} from './element-docs-map.js';
 import {MarkdownTable} from './markdown-tree-builder.js';
 
-type DocFileName = keyof typeof docsToElementMapping;
-
 interface MarkdownTableSection {
   name: string;
   table: MarkdownTable;
@@ -40,7 +38,7 @@ async function updateApiDocs() {
   // Analyzes the entire material-web repository.
   const analyzer = createPackageAnalyzer(packagePath as AbsolutePath);
   const documentationFileNames =
-      Object.keys(docsToElementMapping) as DocFileName[];
+      Object.keys(docsToElementMapping);
 
   const filesWritten: Array<Promise<void>> = [];
 
@@ -66,7 +64,7 @@ async function updateApiDocs() {
  * @returns A promise that resolves when the file has been updated.
  */
 async function updateDocFileApiSection(
-    docFileName: DocFileName, analyzer: Analyzer, packagePath: string) {
+    docFileName: string, analyzer: Analyzer, packagePath: string) {
   const elementEntrypoints = docsToElementMapping[docFileName];
   // This is a data structure that describes an element and its associated API
   // tables. e.g. a single section for MdFilledButton represents MdFilledButton