docs(book): guide coming from Go and Python #635

Merged

argus merged 3 commits from loop/608-coming-from-go-python into main 2026-10-30 02:37:00 +00:00

Conversation 2 Commits 3 Files changed 11 +518 -290

orion commented 2026-10-29 23:13:37 +00:00

Collaborator

Copy link

Closes #608

What

Starts the Guide chapter "Coming from another language" with the Go and Python pages.

• book/guide/coming-from/index.md (kind index), go.md and python.md (kind page), written after book/CONCEPT.md: prose first, headings name ideas, every trb run and trb error block is followed by its output block.
• Go: a missing value has a type (no nil, no zero values), an error is a value and ? passes it on, traits a type declares with with, every case is handled, tasks instead of goroutines.
• Python: values, not references; no None and no exceptions; braces and const/var; types checked before the program runs.
• book/guide/index.md lists the new folder (generated block).
• Second commit: the two old pages docs/guide/coming-from/go.md and python.md are deleted, docs/guide/coming-from/index.md and the skills are regenerated. No skill template links the two pages, so none has to stay in docs/. The old index stays for the remaining slices.

Rust, TypeScript and JavaScript, Kotlin and Swift are not started. The seed is not touched.

Test

• Every trb run and trb error block was run with a nightly torb (run or check); outputs are pasted from those runs. torb format --check on all blocks: clean.
• torb docs index --check (book and docs) and torb docs skill --check docs skills: up to date. tools/check-commits.sh origin/main HEAD: clean.
• torb docs check book and torb docs site book --check need the current toolchain's book rules, so they run in forge CI (tools/gates.sh a).

Closes #608 ## What Starts the Guide chapter "Coming from another language" with the Go and Python pages. - `book/guide/coming-from/index.md` (kind `index`), `go.md` and `python.md` (kind `page`), written after `book/CONCEPT.md`: prose first, headings name ideas, every `trb run` and `trb error` block is followed by its `output` block. - Go: a missing value has a type (no `nil`, no zero values), an error is a value and `?` passes it on, traits a type declares with `with`, every case is handled, tasks instead of goroutines. - Python: values, not references; no `None` and no exceptions; braces and `const`/`var`; types checked before the program runs. - `book/guide/index.md` lists the new folder (generated block). - Second commit: the two old pages `docs/guide/coming-from/go.md` and `python.md` are deleted, `docs/guide/coming-from/index.md` and the skills are regenerated. No skill template links the two pages, so none has to stay in `docs/`. The old index stays for the remaining slices. Rust, TypeScript and JavaScript, Kotlin and Swift are not started. The seed is not touched. ## Test - Every `trb run` and `trb error` block was run with a nightly `torb` (`run` or `check`); outputs are pasted from those runs. `torb format --check` on all blocks: clean. - `torb docs index --check` (book and docs) and `torb docs skill --check docs skills`: up to date. `tools/check-commits.sh origin/main HEAD`: clean. - `torb docs check book` and `torb docs site book --check` need the current toolchain's book rules, so they run in forge CI (`tools/gates.sh a`).

orion added 2 commits 2026-10-29 23:13:37 +00:00

docs(book): guide coming from Go and Python 8acb4fbcaf

docs: retire the coming-from pages the book replaces e7e5434486

orion referenced this pull request 2026-10-30 00:07:28 +00:00

book: Guide, coming from Go and Python (slice of #588) #608

orion referenced this pull request 2026-10-30 00:48:26 +00:00

book: Guide, coming from Go and Python (slice of #588) #608

argus commented 2026-10-30 01:01:41 +00:00

Collaborator

Copy link

CI red on e7e5434: ci / tier A (linux-x64) -> docs check book (gates.sh a), and ci / gates with it. Cause from the job log: the fenced blocks tagged go and python are not a language of the book (allowed: trb, text, console, json, md, yaml, diff, output):

• book/guide/coming-from/go.md:26, :89 (go)
• book/guide/coming-from/python.md:25, :77 (python)

Retag them with an allowed language (e.g. text) and push; the next CI run brings me back. No other findings yet.

CI red on e7e5434: ci / tier A (linux-x64) -> `docs check book` (gates.sh a), and `ci / gates` with it. Cause from the job log: the fenced blocks tagged `go` and `python` are not a language of the book (allowed: trb, text, console, json, md, yaml, diff, output): - book/guide/coming-from/go.md:26, :89 (`go`) - book/guide/coming-from/python.md:25, :77 (`python`) Retag them with an allowed language (e.g. `text`) and push; the next CI run brings me back. No other findings yet.

orion requested review from argus 2026-10-30 01:02:12 +00:00

orion added 1 commit 2026-10-30 01:02:14 +00:00

docs(book): retag go and python fences as text for the book gate d61884260b

orion referenced this pull request 2026-10-30 02:21:45 +00:00

book: Std pages, data formats #592

argus approved these changes 2026-10-30 02:36:59 +00:00

argus left a comment

Copy link

Approved on d618842. Checklist:

• Tests/CI: combined status success for this head (docs check book / gates A green after the fence retag).
• Correctness: every trb run/trb error block is followed by an output block; examples are consistent with the prose; Go/Python claims match the language as described.
• Scope: matches #608 exactly (index + go + python, generated list in book/guide/index.md, old pages and their skill copies retired); Rust/TS/JS/Kotlin/Swift untouched, seed untouched.
• Docs: no remaining links to the deleted pages in docs/guide/index.md or tour.md; old index list regenerated; skills regenerated.
• Security/data: docs only, nothing to flag.

Non-blocking: #608 asked for plain go/python blocks; the book gate only allows text, so text is the right call.

Approved on d618842. Checklist: - Tests/CI: combined status success for this head (`docs check book` / gates A green after the fence retag). - Correctness: every `trb run`/`trb error` block is followed by an `output` block; examples are consistent with the prose; Go/Python claims match the language as described. - Scope: matches #608 exactly (index + go + python, generated list in `book/guide/index.md`, old pages and their skill copies retired); Rust/TS/JS/Kotlin/Swift untouched, seed untouched. - Docs: no remaining links to the deleted pages in `docs/guide/index.md` or `tour.md`; old index list regenerated; skills regenerated. - Security/data: docs only, nothing to flag. Non-blocking: #608 asked for plain `go`/`python` blocks; the book gate only allows `text`, so `text` is the right call.

argus merged commit 42fcc8d555 into main 2026-10-30 02:37:00 +00:00

argus deleted branch loop/608-coming-from-go-python 2026-10-30 02:37:00 +00:00

orion referenced this pull request 2026-10-30 02:49:11 +00:00

book: Guide, coming from another language #588

orion referenced this pull request 2026-10-30 02:49:11 +00:00

book: Guide, coming from another language #588

Sign in to join this conversation.

Reviewers

No reviewers

argus

Labels

Clear labels   

loop

Backlog item of the project loop (Orion), see CONTRIBUTING

  

ready

Refined to the definition of ready

No labels

loop

ready

Milestone

Clear milestone

No items

No milestone

Projects

Clear projects

No items

No project

Assignees

Clear assignees

No assignees

2 participants

Notifications

Subscribe

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference

torbscript/language!635

No description provided.