Update docs and examples for deliberate API changes

[rtibbles]

❌ This issue is not open for contribution. Visit Contributing guidelines to learn about the contributing process and how to find suitable issues.

Overview

Several deliberate breaking changes are still undocumented, or still documented in their old form: one primary file per node, a required ka_language, the removal of downloader and utils.utils, shifted positional arguments, and the removal of validate_tree. Removed options also fail badly: --resume crashes with a traceback, and CHANNEL_ID is silently ignored.

Complexity: Medium
Target branch: main

Context

• chefs.py:308: --resume raises the following, and --step=LAST is passed to construct_channel as a keyword argument (cf9c67d):

  ValueError: not enough values to unpack (expected 2, got 1)
  

• channel_info["CHANNEL_ID"] is ignored, so the chef uploads to a new channel (c152448, Revert "Allow for chefs to explicitly set a channel ID." #582).
• Overriding run() to call uploadchannel directly raises AttributeError: 'Chef' object has no attribute 'auth' (8af9b68), even though docs/developer/design_cli.md still describes this.
• Still documenting removed APIs:
  • docs/downloader.md, docs/parsing_html.md and docs/htmlapps.md: ricecooker.utils.downloader.
  • docs/nodes.md:286: PerseusQuestion without ka_language.
  • docs/developer/uploadprocess.md: validate_tree.
• The 4th positional argument of ContentNode/ExerciseNode is now uri, and the 6th of TopicNode is copyright_holder.
• Nodes with two primary files (high- plus low-res video, PDF plus EPUB) are rejected with Multiple (2) required presets found (cb7ba7c).

The Change

• Docs and examples should match the current API: one primary file per node, a required ka_language, the page archiving that replaced downloader, the utils.utils → validators/paths moves, keyword-only arguments, and no validate_tree.
• Removed options should fail loudly instead of crashing or being ignored.

How to Get There

Run ./sushichef.py --resume.

Out of Scope

• Bringing back resume, or multiple primary files per node.

Acceptance Criteria

• --resume and --step exit with a message saying they were removed.
• CHANNEL_ID in channel_info warns or fails.
• Overriding run() to call uploadchannel works, or design_cli.md stops describing it.
• No page under docs/ references ricecooker.utils.downloader, ricecooker.utils.utils or validate_tree, or shows positional node arguments.
• Every chef under examples/ builds its tree and passes validation offline.

AI usage

I directed the regression hunt and decided which behaviour changes were intended; Claude Code compared v0.7.3 against main, reproduced each regression with scripts, and drafted this issue.

[rtibblesbot]

@rtibbles Design decisions for #783; I'll go ahead with these unless you say otherwise.

Removed options

• --resume and --step: register them as hidden argparse flags. Either one raises InvalidUsageException saying it was removed. Also catch ValueError in the key=value loop, which currently only catches IndexError, so any stray --flag gets the "Invalid option" message instead of a traceback.
• CHANNEL_ID in channel_info: get_channel fails with InvalidUsageException. The message says the ID is derived from CHANNEL_SOURCE_DOMAIN + CHANNEL_SOURCE_ID and prints the derived ID. I chose fail over warn because warning would still upload to a new channel (Revert "Allow for chefs to explicitly set a channel ID." #582 revert).
• run() override: make it work. uploadchannel builds chef.file_pipeline / chef.auth when run() didn't. Also fix design_cli.md's stale args.__dict__ snippet.

Docs

• Rewrite downloader.md, parsing_html.md and htmlapps.md around page archiving (ContentNode(uri=...)).
• nodes.md: add ka_language; state the one-primary-file rule.
• uploadprocess.md: drop validate_tree.
• Move utils.utils references to validators/paths, and switch every node example to keyword arguments.
• history.rst stays as it is (changelog).

Examples

• Rewrite wikipedia to use uri= page archiving instead of utils.html.download_file, so construct_channel only fetches the two list pages.
• Add a parametrized test in tests/test_chef_integration.py over examples/*/sushichef.py. It builds the tree and validates every node with the network blocked; the wikipedia list pages replay from a VCR cassette.

[rtibblesbot]

Plan: Removed options fail loudly, run() overrides work again, and docs plus examples match the current API, with every example chef tested offline.

• Reject removed CLI flags and stray --flags
• Reject CHANNEL_ID in channel_info
• uploadchannel builds pipeline and auth for run() overrides
• Every example chef builds and validates offline
• Page-archiving docs replace downloader
• Correct the node API docs
• Self-review the produced code

Assumptions — the issue did not settle these; say so if one is wrong.

• CHANNEL_ID fails even when equal to the derived ID; if wrong, allow the equal case.
• Wikipedia cassette is hand-written, since the sandbox blocks en.wikipedia.org; if wrong, re-record and fix parsing for the live table.
• Wikipedia nodes switch from Public Domain to CC BY-SA "Wikipedia contributors"; if wrong, restore PublicDomainLicense().
• Wikipedia drops its .webcache CacheControl session; if wrong, re-add it and the test writes .webcache to the repo root.
• key=a=b options now get "Invalid option" instead of a traceback; if values may contain =, split on the first =.
• run() overrides still archive their tree as chefdata/trees/None.json; if wrong, move run-id setup into uploadchannel.
• studiocontent keeps DocumentNode/AudioNode with File objects; if wrong, convert it to ContentNode(uri=...).

---

@rtibblesbot's comments are generated by an LLM, and should be evaluated accordingly

How was this generated?

• Implemented code following the pre-approved plan using test-driven development (red-green-refactor)
• Ran the project's full test suite and linter before committing
• For UI changes: captured live screenshots to verify rendering
• For backend changes: verified with example API/CLI output