Docs/reorganize topic layout - #78
Conversation
Restructure the documentation tree so each topic's guide, design doc and dev doc live together, and archive superseded material instead of leaving it scattered across the repo root and docs/ root. New layout: docs/guide/ foundation guides 00-04 docs/topics/<NN-X>/ one folder per topic (guide + design + dev) docs/reference/ ARCHITECTURE, developer/optimization/verification, coding standards docs/reports/ topic reports and schedules docs/plans/ implementation plans docs/promo/ recruitment page (md + html) docs/archive/提案/ 29 archived topic proposals docs/archive/旧版/ superseded versions (topic17 v1.3, old landing page) 103 files moved, 205 relative links rewritten, no content deleted. The course-site generator keys output filenames on num+title rather than on the markdown's directory, so the move is neutral for the published site: the 42 generated pages are byte-identical before and after. Only 16 hrefs change, 13 of them reference docs following the files into docs/reference/. Also: - docs/topics/html/ is a build artifact that CI never refreshed (it builds to benchmark_reports/docs), so it drifted from the sources. Untrack it, gitignore it, and add a `make docs` target. - Drop the never-hit basename fallback in _md_link_to_html: with several docs legitimately sharing a basename it would silently resolve links to the wrong page. - Fail the build when a COURSE doc is missing and wipe stale output. The previous WARNING-and-continue emitted dead sidebar links while CI stayed green. - Add scripts/check_docs_links.py, wired into CI: validates relative links, basename uniqueness, and emitted GitHub blob URLs. - Fix 4 pre-existing broken links in archived proposals. Co-Authored-By: Claude <noreply@anthropic.com>
The reorganisation is complete and verified, so migrate_docs_layout.py has no further use. Its two-phase MOVES table is preserved in the parent commit (5a98471) for anyone auditing the file moves. scripts/check_docs_links.py stays -- it is wired into CI. Co-Authored-By: Claude <noreply@anthropic.com>
The docs under docs/topics/ read as long tutorials, which makes them a poor entry point for someone picking up a topic. The original topic proposals in docs/archive/提案/ already read as a guide -- difficulty, status, one-line overview, task list, deliverables and a 12-week plan -- so for the 18 topics that have one, the proposal now serves as the topic's main document and the previous guide is renamed NN-X-详细教程.md and kept beside it. 18 main documents swapped; the other 12 topics (3, 8, 10, 15, 19, 23-27, 29, 30) have no proposal and are untouched. Because the generator points at docs/topics/<NN-X>/<NN-X>.md, the course site picks up the shorter documents with no path changes: still 42 pages, and exactly the 18 swapped pages differ from the previous build. Cross-references needed care. A link like "相关课题: 课题17" means "topic 17's document", and that path is unchanged -- it just holds different content now. Rewriting it to follow the old file to -详细教程.md would have pointed 62 cross-references and all of docs/topics/INDEX.md at the detailed version, inverting the intent, so those were reverted. Only references that are explicitly about the tutorial keep pointing at -详细教程.md. Also fixes stale link labels: where a label was itself a path (e.g. ../../../topic13/README.md) it is now the current name. Labels that are accurate repo-relative paths (benchmark_reports/peephole_compare.md) are left as-is -- they are descriptions, not paths. Co-Authored-By: Claude <noreply@anthropic.com>
The swap is done and verified; the mapping is preserved in the parent commit (fb5d2fd) for anyone auditing it. scripts/check_docs_links.py stays. Co-Authored-By: Claude <noreply@anthropic.com>
The project started with 14 topics (2026-05-21 task specs, implemented in PR #5); the rest were added later and grew doc/topics to 30. docs/topics now holds the first phase only, and the 16 later topics move to docs/archive/后续课题/ -- moved, not deleted. docs/topics/ 14 topics (01 05 06 07 09 11 12 13 14 17 18 20 21 28) docs/archive/后续课题/ 16 topics (02 03 04 08 10 15 16 19 22-27 29 30) 20 files moved, 47 links rewritten. The course site follows: the 16 are dropped from COURSE, so it builds 25 pages instead of 42 (1 index + 5 sections + 5 foundation + 14 topics). The "规划中" section had all three of its topics archived and is removed -- an empty section is just an empty promise. Section descriptions no longer advertise topics that left. docs/topics/INDEX.md is rewritten as the first-phase index and gains a section pointing at the archived 16, so nothing becomes undiscoverable. It also now links topic 06's guide rather than 06-性能测试套件使用说明.md, which is what COURSE had been pointing at -- the two had disagreed. Two latent bugs surfaced while updating the promo page: - docs/promo/ScratchV.html had 14 dead GitHub blob links. Its table has an "实现指南" and a "提案" column; once the proposals became the guides, the 提案 column pointed at files that no longer exist. That column now points at the demoted -详细教程.md and is labelled accordingly. - check_docs_links.py only validated blob URLs under --html-dir, so an absolute GitHub URL in a hand-maintained page was never checked -- exactly the kind of link that rots unnoticed when files move. It now scans every tracked .html. Verified against an injected dead link. Co-Authored-By: Claude <noreply@anthropic.com>
Mapping preserved in the parent commit. scripts/check_docs_links.py stays. Co-Authored-By: Claude <noreply@anthropic.com>
The 18 -详细教程.md files were the pre-swap guides, demoted when the topic proposals became the guides. They are removed, along with the 12 later-phase topics on docs/archive/后续课题/ whose only document was that same overly detailed guide -- 30 files in total. docs/topics/ 14 topics keep guide + design/dev docs docs/archive/后续课题/ only 02, 04, 16, 22 keep a document (03 08 10 15 19 23-27 29 30 are gone from the working tree) All 30 remain in git history; nothing was rewritten. Reference clean-up: - docs/reference/ARCHITECTURE.md linked three deleted topics in its "深入学习" line; it now points at the topics index. - docs/topics/13-窥孔优化器/ referenced its 详细教程 in four places (completion index, reading order, design doc header, guide header). - docs/topics/INDEX.md's archive table listed all 16 later topics; it now lists the 4 that still have documents and says where the other 12 went. - CLAUDE.md no longer advertises a 详细教程 role. docs/promo/ScratchV.html had its 课题提案 column relabelled to 详细教程 in the previous commit; with those files gone the column had no target, so the column (header + 14 cells) is removed. The table is back to four columns. check_docs_links.py caught all 19 relative links and 14 blob URLs this deletion broke, which is what it is for. Co-Authored-By: Claude <noreply@anthropic.com>
Both directories held per-topic material that belonged with its topic, so
docs/reports/ and docs/plans/ are gone and their 7 files sit in the topic
folders:
06-性能基准套件/ 06-双后端未通过用例分析.md
17-寄存器分配/ 17-寄存器分配-{AI自审报告,P1实现报告,伪指令溢出统计排期,修改测试自查报告}.md
01-DSL前端增强器/ 01-DSL前端增强器-CI-Benchmark实现计划-2026-09-19.md
09-DSL错误提示美化器/ 09-DSL错误提示美化器-实现计划-2026-08-12.md
None of the 7 had an inbound link or an outbound relative link, so nothing
needed rewriting. The plan files were renamed to the topic-folder convention;
their original names carried the only date record, so it is kept as a suffix
rather than dropped.
docs/ is now only guide/ topics/ reference/ promo/ archive/ plus the index.
Co-Authored-By: Claude <noreply@anthropic.com>
The v1.3 design and dev docs sat in docs/archive/旧版/ because v1.5 superseded them. They belong with topic 17 like its other documents, so both move to docs/topics/17-寄存器分配/ and keep their version-suffixed names, so v1.3 and v1.5 sit side by side and the older one is still identifiable. Neither file had an inbound link or an outbound relative link, so nothing needed rewriting. docs/archive/旧版/ now holds only the archived landing page. Co-Authored-By: Claude <noreply@anthropic.com>
15 files removed: the 11 module guides left in 提案/ and the 4 later-phase topics still holding a document in 后续课题/ (02, 04, 16, 22). All remain in git history. They had 15 inbound references between them, which had to be dealt with rather than left dangling: - docs/promo/ScratchV.html pointed its 实现指南 column at the archived module guides for 7 of the 14 topics. Those now point at the topic's own guide, so all 14 rows are consistent and none point into archive/. - docs/topics/13-窥孔优化器/ referenced topic13_asm_peephole_guide.md in four places (completion index, reading order, design doc header, and the closing maintenance pointer). The completion index was already removed earlier; the remaining three go, and the closing pointer now points at the topic's own completion index. - docs/topics/INDEX.md loses its 后续课题 section, which listed topics whose documents no longer exist. docs/archive/ now holds only the archived course landing page. Co-Authored-By: Claude <noreply@anthropic.com>
🤖 AI Code Review
📁
|
2 participants
No description provided.