[codex] Refine language documentation structure#1202
Draft
peter-jerry-ye wants to merge 6 commits into
Draft
Conversation
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
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.
Summary
Rework this draft from a one-heading-one-page split into a whole-section documentation structure:
next/language/index.mdso the language section is organized by reader intent and topic areatests.mdasTesting and Benchmarking, because benchmarks are written through test blocksasync.md; keepasync-experimental.mdas an orphan compatibility pagebenchmarks.mdas an orphan compatibility page that points totests.md#writing-benchmarkstutorial/as the learning path andtoolchain/as tool manualsfundamentalsinto six grouped concept pages instead of nine tiny pagesfundamentals.mdas the section index and old-anchor topic indexnext/llm.pyso rendered markdown summaries use Sphinx’s resolvedenv.toctree_includesinstead of parsing source toctree blocksThe resulting
fundamentalspages are:Rationale
This follows the progressive direction discussed in review: the language section should behave like a manual/reference area, while tutorial pages can be more book-like. The split is intentionally coarser than the first draft: it improves scanability and linkability without turning every subsection into a navigation stop. The grouped toctrees make the manual organization visible in navigation instead of only splitting one large page.
I did not physically merge methods, derive, and attributes because together they would become a large mixed reference page. They are now grouped as core language mechanisms, which gives readers the intended relationship while keeping each reference page focused. Tests and benchmarks are physically merged because they are short and share the same execution model.
Useful grounding:
Review notes
This PR intentionally keeps the change source-only. Translation catalog migration should be handled separately; syncing catalogs in the same PR would add broad generated
.pochurn and obscure the structural review.The downloadable markdown summaries are generated at build time. The PR updates the generator, not the generated
next/download/*/summary.mdfiles.Validation
just docs-htmlcd next && uv run --with-requirements requirements.txt python llm.pyBoth commands succeed. Remaining warnings are pre-existing download-summary or markdown-builder warnings.