Update docs and examples for deliberate API changes #783

❌ 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.