Skip to content

[codex] Refine language documentation structure#1202

Draft
peter-jerry-ye wants to merge 6 commits into
mainfrom
codex/split-language-fundamentals
Draft

[codex] Refine language documentation structure#1202
peter-jerry-ye wants to merge 6 commits into
mainfrom
codex/split-language-fundamentals

Conversation

@peter-jerry-ye
Copy link
Copy Markdown
Collaborator

@peter-jerry-ye peter-jerry-ye commented May 8, 2026

Summary

Rework this draft from a one-heading-one-page split into a whole-section documentation structure:

  • add a visible manual map to next/language/index.md so the language section is organized by reader intent and topic area
  • split the language toctree into grouped navigation blocks: Orientation, Core language mechanisms, Packages and development, Interop and advanced topics, and Reference
  • group methods, derive, attributes, and error handling as core language mechanisms without physically merging those reference pages
  • merge benchmark content into tests.md as Testing and Benchmarking, because benchmarks are written through test blocks
  • rename the active async page to async.md; keep async-experimental.md as an orphan compatibility page
  • keep benchmarks.md as an orphan compatibility page that points to tests.md#writing-benchmarks
  • keep tutorial/ as the learning path and toolchain/ as tool manuals
  • split fundamentals into six grouped concept pages instead of nine tiny pages
  • update internal links to moved pages while keeping fundamentals.md as the section index and old-anchor topic index
  • update next/llm.py so rendered markdown summaries use Sphinx’s resolved env.toctree_includes instead of parsing source toctree blocks

The resulting fundamentals pages are:

  • built-ins and literals
  • functions
  • control flow and iteration
  • custom data types
  • pattern matching
  • special syntax

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 .po churn 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.md files.

Validation

  • just docs-html
  • cd next && uv run --with-requirements requirements.txt python llm.py

Both commands succeed. Remaining warnings are pre-existing download-summary or markdown-builder warnings.

@peter-jerry-ye peter-jerry-ye changed the title [codex] Split language fundamentals into focused pages [codex] Refine language documentation structure May 8, 2026
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