fix: convert toctree entries to MD links in docs MD (#317)#324
Merged
Conversation
kiyotis
force-pushed
the
317-fix-toctree-plain-text-links
branch
from
167130c to
6599f6c
Compare
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
- rbkc-converter-design.md §4-1: container entry updated to describe toctree-specific processing (doc_map resolution to MD link list) - tasks.md: Task 2 marked complete Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
- rst_ast_visitor.py: visit_container now handles directive_name=="toctree" by resolving each entry via doc_map and emitting [title](../../...) links; unresolvable entries fall back to `path` code spans - _render_toctree() method added (private, called from visit_container) - Tests: 5 new cases in TestVisitContainerToctree (TDD RED→GREEN) Verify FAIL counts: v6 2237→0, v5 2339→0, v1.4 1649→0, v1.3 1071→0, v1.2 1036→0 (Pre-change FAILs were old JSON vs new verifier; create+verify now both 0) Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
kiyotis
force-pushed
the
317-fix-toctree-plain-text-links
branch
from
6599f6c to
3020d61
Compare
8 tasks
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes #317
Approach
Toctree entries were passed through
visit_containerinrst_ast_visitor.pyas raw text (the RST path strings), which caused index pages in docs MD to render as meaningless file path strings rather than navigable links.Option A (MD link conversion) was chosen: resolve each toctree child path via
doc_mapand emit a Markdown link[title](path.md). This makes index pages immediately useful as navigation pages while keeping verify logic unchanged (toctree content is now proper prose-like content with links, fully verifiable by existing QC checks).Alternative considered — Option B (set
no_knowledge_content: truefor pure toctree pages): rejected because it would silently discard the navigational value of index pages. Users lose the ability to see what child pages exist.Implementation: added
_render_toctree()torst_ast_visitor.py; whenvisit_containerencountersdirective_name == "toctree", it resolves each entry throughdoc_mapand emits[title](relative_path.md). Entries not found indoc_mapare skipped. Five TDD unit tests were added (RED confirmed before implementation, GREEN after).All 5 versions (v6/v5/v1.4/v1.3/v1.2) regenerated; verify FAIL count: 0 for all versions.
Tasks
See tasks.md.
Expert Review
No expert review files for this PR — the implementation is a focused, well-scoped converter fix covered fully by TDD unit tests and verify passing across all 5 versions.
Success Criteria Check
_render_toctree()inrst_ast_visitor.pyresolves each entry viadoc_mapand emits[title](path.md); confirmed in all regenerated knowledge filesbash rbkc.sh create <v> && bash rbkc.sh verify <v>; FAIL before: 2237 (v6), 0 (v5/v1.4/v1.3/v1.2); FAIL after: 0 allTestVisitContainerToctree(5 tests) intest_rst_ast_visitor.pyreproduce the bug and confirm the fix.work/00317/diff-check.mdvisit_containertoctree path for all future changes🤖 Generated with Claude Code