Skip to content

feat: improve Doxygen HTML migration lane#699

Open
shczhen wants to merge 18 commits into
codex/html-migration-typedocfrom
codex/html-migration-doxygen
Open

feat: improve Doxygen HTML migration lane#699
shczhen wants to merge 18 commits into
codex/html-migration-typedocfrom
codex/html-migration-doxygen

Conversation

@shczhen

@shczhen shczhen commented Jul 9, 2026

Copy link
Copy Markdown
Collaborator

Summary

  • Add Doxygen/Javadoc lane filtering so generated helper pages do not become migrated docs pages.
  • Render Doxygen member pages semantically from .memtitle, .memitem, .memproto, .memdoc, dl.params, and dl.return.
  • Keep Javadoc-compatible fallback behavior when Doxygen member selectors are not present.

Closes #694.

Details

  • Filters Doxygen helper/index artifacts such as *-members.html, *_source.html, functions*, namespacemembers*, and globals* from the migration plan.
  • Preserves stable Doxygen member anchors as <a id="..."></a>.
  • Emits C++ signatures as fenced code blocks.
  • Emits parameter and return sections as Markdown tables/sections instead of flattened prose.
  • Keeps existing public CLI behavior through node scripts/html-to-md-migration.mjs.

Verification

  • node --check scripts/html-to-md-migration.mjs
  • bun run test scripts/html-to-md-migration.test.ts
  • bun x biome check scripts/html-to-md-migration.mjs scripts/html-to-md-migration.test.ts scripts/html-migration
  • node scripts/html-to-md-migration.mjs --source /Users/czhen/Documents/GitHub/AgoraIO/shengwang-doc-source/html-docs/recording/cpp --output /tmp/check-doxygen-recording-cpp-new --product recording --platform cpp --route-base-path /zh-CN/api-reference --dry-run
  • node scripts/html-to-md-migration.mjs --source /Users/czhen/Documents/GitHub/AgoraIO/shengwang-doc-source/html-docs/recording/cpp --output /tmp/check-doxygen-recording-cpp-full --product recording --platform cpp --route-base-path /zh-CN/api-reference
  • node scripts/html-to-md-migration.mjs --source /Users/czhen/Documents/GitHub/AgoraIO/shengwang-doc-source/html-docs/rtc/Android --output /tmp/check-dita-rtc-android --product rtc --platform android --route-base-path /zh-CN/api-reference --dry-run
  • bun run types:check

Stack

This PR is stacked on #698 because #694 depends on the lane dispatcher introduced there. After #698 merges, this PR can be retargeted to main.

@github-actions

github-actions Bot commented Jul 9, 2026

Copy link
Copy Markdown

Vercel Preview

Preview URL: https://docs-portal-p6imwvafw-agora-devx.vercel.app

@shczhen

shczhen commented Jul 12, 2026

Copy link
Copy Markdown
Collaborator Author

已同步 #724 的迁移器修复(commit 241fa2c3,以实际推送 commit 为准):Doxygen helper/index 页面继续生成并保留链接,但从 root/nested meta.json 导航中隐藏。该 PR 基线专项测试 10/10、Biome、git diff --check 通过;完整 hierarchy.html 真实源覆盖在后续栈 PR #712 验证。PR 保持未合并。

@shczhen

shczhen commented Jul 12, 2026

Copy link
Copy Markdown
Collaborator Author

更正:上述同步提交的实际 commit 为 1cd293ad

@shczhen

shczhen commented Jul 12, 2026

Copy link
Copy Markdown
Collaborator Author

已同步 #725(commit HEAD):Doxygen alphabet index 使用不可见 anchor target 加可读字母标题,保留跳转与符号链接。该 PR 基线测试 10/10、Biome、git diff --check 通过;PR 保持未合并。

@shczhen

shczhen commented Jul 14, 2026

Copy link
Copy Markdown
Collaborator Author

Issue #760 已在本 PR 修复:178bd6a39 为 Doxygen/Javadoc API 根生成 scoped navigation;541a9586f 保留 doxygen_crawl.html 路由但从导航隐藏。迁移测试 12/12 通过,生成内容及真实六路由运行时测试已同步到 PR #712

@shczhen

shczhen commented Jul 14, 2026

Copy link
Copy Markdown
Collaborator Author

已在原 PR 更新 #724/#725/#729/#730:修正 hierarchy Doxygen 识别、helper/字母索引输出、Doxygen 邮件解码,以及显式锚点确定性去重和同页链接重写;fenced/inline/跨行 code 均受保护。真实 rtc-server-sdk/cpp 368 个 MDX duplicate_ids=0,RTSA C 无 nosp@m/](#);专项 13/13、types:check、Standards/Spec 审查通过。PR 保持未合并。

@shczhen

shczhen commented Jul 14, 2026

Copy link
Copy Markdown
Collaborator Author

对应 #771 的根因修复已推送:518aa6ae0。新增 cheerio 根级直接开发依赖;干净 frozen install、真实 Doxygen dry-run(37 个文件)及迁移测试 13/13 均通过。请 doc team 继续测试,PR 不合并。

@shczhen

shczhen commented Jul 14, 2026

Copy link
Copy Markdown
Collaborator Author

已将本 stacked PR 重放到当前 #698 head,消除父分支冲突;当前 head 2150e7b7b,merge state CLEAN。验证:22/22 迁移测试、类型检查、Biome、真实 Doxygen 37-file dry-run 通过。未合并,继续供 doc team 测试。

@shczhen

shczhen commented Jul 14, 2026

Copy link
Copy Markdown
Collaborator Author

#775 已在本 PR 修复并推送至 60e817cda

  • 修正含 modules.html 的 Doxygen 树被误判为 TypeDoc/0 页。
  • 正常迁移后幂等登记产品级与 Reference 级祖先导航,保证从旧基线重跑也能解析局部侧栏。
  • 新增两条 CLI 回归测试;迁移测试 24/24、types:check、Biome、node --checkgit diff --check 通过。

未改生成内容、未处理 #774 的 DocsShell、未合并 PR;待 doc team 测试。

@shczhen

shczhen commented Jul 14, 2026

Copy link
Copy Markdown
Collaborator Author

复核 Issue #786:当前分支所含 a5ffeec 已覆盖嵌套 content/docs/zh-CN 输出路径。Recording C++ 同源重跑 locale-less 内链 0、本地化内链 483,无需新增代码,待复测。

@shczhen

shczhen commented Jul 14, 2026

Copy link
Copy Markdown
Collaborator Author

已在本 PR 更新 #787/#788:Doxygen class description 完全重复时去重,并仅在 zh-CN 本地化成员详情标签。提交 51de0ce。真实 Recording C++ 37 页重跑、25 个迁移测试、类型检查和双轴审查通过,待文档团队复测。

@shczhen

shczhen commented Jul 14, 2026

Copy link
Copy Markdown
Collaborator Author

#790 复核:当前本 PR 对 Recording C++ 同源重跑 38 个 MDX,正文 H1=0。反馈中的第二个 DOM H1 来自旧 baseline DocsShell 双挂载,根修复在汇总 PR #712;未在 Doxygen 内容层做 workaround。待基于 #712 完整 head 复测。

@shczhen

shczhen commented Jul 14, 2026

Copy link
Copy Markdown
Collaborator Author

#799 已在本 PR 原分支修复(35ffaf543):Doxygen 签名按 platform 正确区分 C/C++ 等并显示语言标题,通用代码块不再按平台误猜。迁移测试 25/25、types、Biome 通过,待文档团队复测。

@shczhen

shczhen commented Jul 14, 2026

Copy link
Copy Markdown
Collaborator Author

#806 已修复:b275f9104 将 DocsShell 响应式正文改为单一 DOM 挂载,4a007c758 增加 Doxygen H1 唯一性回归。根因在 shell 双挂载,不在生成内容;没有 H1 删除 workaround。

验证:专项 2/2、migration 25/25、DocsContent 48/48、types、Biome、diff check、双轴审查均通过。请从本 PR 最新 head 复测。

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant