From d8222d850e77c736b6154eb96d0efa0037a47a8b Mon Sep 17 00:00:00 2001 From: Sy Bohy Date: Thu, 18 Jun 2026 12:11:49 -0700 Subject: [PATCH] feat: scaffold Android reference doc generator (no-op stub) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The Android counterpart of mintlify-codegen/ios-reference/. Adds a no-op generate.ts + README so the seamapi/phone Android docs-sync workflow can run end-to-end safely while the real Dokka→MDX generator is built. The stub accepts --archive and exits 0 without writing any files, so the sync workflow is a safe no-op — the hand-authored Android reference pages (DOC-231) are never overwritten. README documents the intended pipeline and the key design decision (which Dokka output to parse). Co-Authored-By: Claude Opus 4.8 --- mintlify-codegen/android-reference/README.md | 52 +++++++++++++++++++ .../android-reference/generate.ts | 52 +++++++++++++++++++ 2 files changed, 104 insertions(+) create mode 100644 mintlify-codegen/android-reference/README.md create mode 100644 mintlify-codegen/android-reference/generate.ts diff --git a/mintlify-codegen/android-reference/README.md b/mintlify-codegen/android-reference/README.md new file mode 100644 index 000000000..11d927a9c --- /dev/null +++ b/mintlify-codegen/android-reference/README.md @@ -0,0 +1,52 @@ +# Android Reference Page Generator (SCAFFOLD) + +The Android counterpart of [`../ios-reference/`](../ios-reference/README.md). When +complete, it will regenerate `mintlify-docs/mobile-sdks/android/reference/*.mdx` +automatically from the Android SDK's Dokka output. + +## Current Status: Not Implemented — Hand-Authored Pages in Place + +> The Android reference MDX pages are currently **hand-authored** (DOC-231, #1155) +> from the public Kotlin API in the `phone` repo +> (`seam-phone-android/seam-phone-sdk-android/core/src/main/java/co/seam/core/api/*.kt`). +> `generate.ts` is a **no-op stub**: it accepts `--archive` and exits 0 without +> writing, so the sync workflow stays a safe no-op and never overwrites those +> pages until the real generator lands. + +## Intended Pipeline + +``` +phone/seam-phone-android/ ← Kotlin SDK (Dokka 1.9.10 configured) + + ./gradlew dokkaHtmlMultiModule ← aggregates each module's dokkaHtmlPartial + ↓ +build/dokka/htmlMultiModule/ ← Dokka output + + tsx mintlify-codegen/android-reference/generate.ts \ + --archive build/dokka/htmlMultiModule + ↓ +mintlify-docs/mobile-sdks/android/reference/*.mdx +``` + +The phone-side workflow is `seamapi/phone` +`.github/workflows/seam-phone-android-documentation.yml` — currently +`workflow_dispatch`-only. Enable its `push:` trigger once this generator works. +The docs-side automerge path (`mintlify-docs/mobile-sdks/**`) and the +`seam-ci-bot[bot]` author gate already cover Android, so no `automerge.yml` +change is needed. + +## Key Design Decision Before Implementing + +Unlike Swift-DocC (which emits clean per-symbol render JSON that +`ios-reference/generate.ts` parses), Dokka 1.9 has no first-class JSON output. +Pick one source to parse and design against a **real Dokka build's output**: + +- **`dokkaHtmlMultiModule`** — HTML; richest but hardest to parse cleanly. +- **`dokkaGfmMultiModule`** (GFM plugin) — Markdown; closest to MDX, likely the + least work. +- **Kotlin public sources** — parse `co.seam.core.api` declarations directly, + skipping Dokka entirely. + +Then mirror `../ios-reference/generate.ts` for the per-type page + index +rendering, and match the structure of the existing hand-authored pages so the +generator's first run is a clean diff rather than a rewrite. diff --git a/mintlify-codegen/android-reference/generate.ts b/mintlify-codegen/android-reference/generate.ts new file mode 100644 index 000000000..bd293e832 --- /dev/null +++ b/mintlify-codegen/android-reference/generate.ts @@ -0,0 +1,52 @@ +/* eslint-disable no-console */ +/** + * Android Reference Page Generator — SCAFFOLD (not yet implemented) + * + * The Android counterpart of `../ios-reference/generate.ts`. When complete it + * will transform Dokka output (from `./gradlew dokkaHtmlMultiModule` in the + * seamapi/phone Android SDK) into + * `mintlify-docs/mobile-sdks/android/reference/*.mdx`. + * + * STATUS: stub. It parses its CLI contract and exits 0 WITHOUT writing any + * files, so the sync workflow is a safe no-op until the real generator lands — + * the hand-authored Android reference pages (DOC-231) are never overwritten. + * + * To implement, see README.md (esp. the Dokka-output design decision) and + * mirror ../ios-reference/generate.ts. + * + * Usage (once implemented): + * tsx mintlify-codegen/android-reference/generate.ts --archive /path/to/dokka/htmlMultiModule + * DOKKA_ARCHIVE=/path/to/dokka/htmlMultiModule tsx mintlify-codegen/android-reference/generate.ts + */ + +import { argv, env, exit } from 'node:process' + +function resolveArchivePath(): string | undefined { + const flagIndex = argv.indexOf('--archive') + if (flagIndex !== -1 && argv[flagIndex + 1] != null) { + return argv[flagIndex + 1] + } + return env['DOKKA_ARCHIVE'] +} + +function main(): void { + const archivePath = resolveArchivePath() + + console.warn( + '[android-reference] Generator not yet implemented — this is a scaffold.', + ) + console.warn( + '[android-reference] No pages written; hand-authored Android reference pages are preserved.', + ) + if (archivePath != null) { + console.warn(`[android-reference] Received --archive: ${archivePath}`) + } + console.warn( + '[android-reference] See android-reference/README.md and ios-reference/generate.ts to implement.', + ) + + // Intentionally write nothing and succeed, so the sync workflow no-ops safely. + exit(0) +} + +main()