Skip to content

Validate generated HTML API migration lanes against real legacy sources #697

Closed as not planned
Closed as not planned
Validate generated HTML API migration lanes against real legacy sources#697
Assignees
shczhen
Labels
P0enhancementNew feature or requestready-for-agentFully specified and ready for an AFK agent

Description

@shczhen
shczhen
opened on Jul 9, 2026

This was generated by AI during triage.

Parent

#690

What to build

Run and document an end-to-end validation matrix for the generated HTML API migration lanes. This issue should confirm that the lane implementations are not merely producing files, but are producing navigable, Fumadocs-compatible API reference content with acceptable fidelity against representative real legacy sources.

Acceptance criteria

  • Run dry-run and full /tmp migration for representative DITA/Oxygen, TypeDoc, Doxygen/Javadoc, iOS doc-generator, and Dartdoc sources.
  • Confirm each output contains index.mdx, meta.json, and expected symbol/page MDX files.
  • Audit generated navigation for obvious helper-page pollution, broken symbol names, duplicate entries, and missing landing pages.
  • Audit sample pages from each lane for signatures, parameters, return values, enum/member docs, notes, code blocks, tables, stable anchors, and internal link rewrites.
  • Copy at least one representative output per lane into a disposable docs-portal validation location and run bun run types:check.
  • Produce a concise validation report with commands, counts, sample files checked, known gaps, and follow-up recommendations.
  • Keep REST/OpenAPI explicitly out of scope and verify those sources still route to the OpenAPI lane or fail with guidance.

Blocked by

#693
#694
#695
#696

Activity

  1. shczhen
    added
    enhancementNew feature or request
    on Jul 9, 2026
  2. shczhen
    self-assigned this
    on Jul 9, 2026
  3. shczhen
    added
    P0
    ready-for-agentFully specified and ready for an AFK agent
    on Jul 9, 2026

  4. shczhen commented on Jul 9, 2026

    @shczhen
    shczhen
    on Jul 9, 2026
    CollaboratorAuthor

    Pre-validation update, 2026-07-09.

    Keep the lane PRs open for review; do not merge as part of this validation note.

    Current stacked PR state:

    Pre-validation already run against representative real sources from /Users/czhen/Documents/GitHub/AgoraIO/shengwang-doc-source:

    Lane Source Detection Input files Planned outputs Full output
    DITA/Oxygen html-docs/rtc/Android DITA-OT/Oxygen API reference (API/ directory) 249 251 250 MDX + 1 meta
    TypeDoc html-docs/flexible-classroom/Web TypeDoc HTML reference 398 407 402 MDX + 5 meta
    Doxygen/Javadoc html-docs/recording/cpp Doxygen/Javadoc HTML reference 37 39 38 MDX + 1 meta
    iOS doc-generator/appledoc html-docs/whiteboard/iOS iOS-doc-generator HTML reference 61 75 68 MDX + 7 meta
    Dartdoc html-docs/agora-chat/Flutter Dartdoc HTML reference 817 902 816 MDX + 86 meta

    Additional checks completed locally:

    • REST/OpenAPI source html-docs/whiteboard/RESTful exits nonzero with the expected unsupported-source guidance.
    • All five generated outputs were copied into a disposable subtree under content/docs/zh-CN/api-reference/__html-migration-validation/, then bun run types:check passed. The temporary subtree was removed afterward.

    Current recommendation for this issue:

    Local evidence note: detailed logs are under /tmp/html-migration-matrix/logs/ on the validation machine.

  5. shczhen commented on Jul 9, 2026

    @shczhen
    shczhen
    on Jul 9, 2026
    CollaboratorAuthor

    Final validation PR opened and kept open for review: #704

    Current stack:

    Validation in #704:

    • node --check scripts/validate-html-api-migration.mjs
    • bun x biome check package.json scripts/validate-html-api-migration.mjs docs/agents/reports/2026-07-09-html-api-migration-validation-matrix.md
    • bun run html:migration:validate

    The matrix runner validated representative real sources for DITA/Oxygen, TypeDoc, Doxygen/Javadoc, iOS doc-generator/appledoc, and Dartdoc, copied outputs into a disposable docs subtree for types:check, and verified REST/OpenAPI stays out of scope with guidance.

  6. shczhen commented on Jul 29, 2026

    @shczhen
    shczhen
    on Jul 29, 2026
    CollaboratorAuthor

    This was generated by AI during triage.

    Closing as superseded. The original HTML migration stack was not merged and has been replaced by the API Center migration delivered in PR #847, including the maintained migration pipeline, navigation generation, provenance checks, and link/fragment audits.

  7. shczhen
    closed this as not plannedon Jul 29, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

P0enhancementNew feature or requestready-for-agentFully specified and ready for an AFK agent

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions